ComponentPage: Add Edit On GitHub buttons to page sections

common/changes/@uifabric/example-app-base/edit-docs-buttons_2018-03-31-00-27.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@uifabric/example-app-base",
+      "comment": "Add new APIs for editing sections on GitHub.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@uifabric/example-app-base",
+  "email": "v-jojanz@microsoft.com"
+}

common/changes/office-ui-fabric-react/edit-docs-buttons_2018-03-31-00-27.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Add new component page prop for editing on GitHub.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "v-jojanz@microsoft.com"
+}

packages/example-app-base/src/components/ComponentPage/ComponentPage.scss

@@ -78,6 +78,23 @@ $dontColor: #A61E22;
     }
   }
 
+  .ComponentPage-usageHeader,
+  .ComponentPage-overviewSectionHeader,
+  .ComponentPage-doSectionHeader {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .ComponentPage-usageHeader {
+    margin-top: 10px;
+    margin-bottom: $componentSubHeadMargin;
+
+    .ComponentPage-subHeading {
+      margin: 0;
+    }
+  }
+
   .ComponentPage-related {
     min-width: 200px;
 
@@ -141,17 +158,7 @@ $dontColor: #A61E22;
     margin-bottom: 20px;
 
     h3 {
-      margin: 16px 0 40px 0;
       @include ms-font-xl;
-
-      &::after {
-        background-color: #a4cf0c;
-        border-radius: 3px;
-        content: '';
-        display: block;
-        height: 8px;
-        margin: 12px 0;
-      }
     }
 
     ul {
@@ -171,9 +178,26 @@ $dontColor: #A61E22;
     &:first-child {
       @include ms-margin-right(120px);
     }
+
+    .ComponentPage-doSectionHeader {
+      margin: 16px 0 0 0;
+
+      h3 {
+        margin: 0;
+      }
+    }
+
+    .ComponentPage-doSectionHr {
+      background-color: #a4cf0c;
+      border-radius: 3px;
+      display: block;
+      height: 8px;
+      margin: 12px 0 40px;
+      border: 0;
+    }
   }
 
-  .ComponentPage-doSection--dont h3::after {
+  .ComponentPage-doSection--dont .ComponentPage-doSectionHr {
     background-color: #e74856;
   }
 

packages/example-app-base/src/components/ComponentPage/ComponentPage.tsx

@@ -6,7 +6,9 @@ import {
 import {
   Link
 } from 'office-ui-fabric-react/lib/Link';
+import { IconButton } from 'office-ui-fabric-react/lib/Button';
 import { MessageBar } from 'office-ui-fabric-react/lib/MessageBar';
+import { TooltipHost } from 'office-ui-fabric-react/lib/Tooltip';
 import './ComponentPage.scss';
 
 export interface IComponentPageSection {
@@ -32,6 +34,47 @@ export interface IComponentPageProps {
   otherSections?: IComponentPageSection[];
   allowNativeProps?: boolean | string;
   nativePropsElement?: string | string[] | undefined;
+
+  /**
+   * Link to the Component root folder on GitHub.
+   * Enables 'View On GitHub' and all 'Edit' buttons.
+   */
+  componentUrl?: string;
+
+  /**
+   * Link to the BestPractices markdown file on GitHub.
+   * Enables the 'Edit Best Practices' button.
+   * Overrides URL from componentUrl.
+   */
+  editBestPracticesUrl?: string;
+
+  /**
+   * Link to the Donts markdown file on GitHub.
+   * Enables the 'Edit Don'ts' button.
+   * Overrides URL from componentUrl.
+   */
+  editDontsUrl?: string;
+
+  /**
+   * Link to the Dos markdown file on GitHub.
+   * Enables the 'Edit Dos' button.
+   * Overrides URL from componentUrl.
+   */
+  editDosUrl?: string;
+
+  /**
+   * Link to the Overview markdown file on GitHub.
+   * Enables the 'Edit Overview' button.
+   * Overrides URL from componentUrl.
+   */
+  editOverviewUrl?: string;
+}
+
+export enum ComponentPageSection {
+  Dos = 0,
+  BestPractices = 1,
+  Donts = 2,
+  Overview = 3,
 }
 
 export class ComponentPage extends React.Component<IComponentPageProps, {}> {
@@ -63,7 +106,10 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
           <div className='ComponentPage-body'>
             { this._getComponentStatusBadges() }
             <div className='ComponentPage-overviewSection'>
-              <h2 className='ComponentPage-subHeading' id='Overview'>Overview</h2>
+              <div className='ComponentPage-overviewSectionHeader'>
+                <h2 className='ComponentPage-subHeading' id='Overview'>Overview</h2>
+                { this._editButton(ComponentPageSection.Overview, this.props.editOverviewUrl) }
+              </div>
               <div className='ComponentPage-overviewSectionContent'>
                 <div className='ComponentPage-overview'>
                   { overview }
@@ -100,7 +146,7 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
     let {
       bestPractices,
       dos,
-      donts
+      donts,
     } = this.props;
 
     if (bestPractices && dos && donts) {
@@ -153,8 +199,8 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
 
   private _getNativePropsInfo(): JSX.Element | undefined {
     if (this.props.allowNativeProps) {
-      let elementString: string | string[] | JSX.Element = this.props.nativePropsElement || 'div',
-        componentString: JSX.Element | undefined;
+      let elementString: string | string[] | JSX.Element = this.props.nativePropsElement || 'div';
+      let componentString: JSX.Element | undefined;
       if (typeof elementString === 'object' && elementString.length > 1) {
         const elementArr = elementString.slice();
         for (let _i = 0; _i < elementArr.length; _i++) {
@@ -196,11 +242,13 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
 
   private _getDosAndDonts(): JSX.Element | undefined {
     let dosAndDonts: Array<JSX.Element> = [];
-
     if (this.props.bestPractices) {
       dosAndDonts.push(
         <div className='ComponentPage-usage' id='BestPractices' key='best-practices'>
-          <h2 className='ComponentPage-subHeading'>Best Practices</h2>
+          <div className='ComponentPage-usageHeader'>
+            <h2 className='ComponentPage-subHeading'>Best Practices</h2>
+            { this._editButton(ComponentPageSection.BestPractices, this.props.editBestPracticesUrl) }
+          </div>
           { this.props.bestPractices }
         </div>
       );
@@ -210,11 +258,19 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
       dosAndDonts.push(
         <div className='ComponentPage-doSections' key='do-sections'>
           <div className='ComponentPage-doSection'>
-            <h3>Do</h3>
+            <div className='ComponentPage-doSectionHeader'>
+              <h3>Do</h3>
+              { this._editButton(ComponentPageSection.Dos, this.props.editDosUrl) }
+            </div>
+            <hr className='ComponentPage-doSectionHr' />
             { this.props.dos }
           </div>
           <div className='ComponentPage-doSection ComponentPage-doSection--dont'>
-            <h3>Don&rsquo;t</h3>
+            <div className='ComponentPage-doSectionHeader'>
+              <h3>Don&rsquo;t</h3>
+              { this._editButton(ComponentPageSection.Donts, this.props.editDontsUrl) }
+            </div>
+            <hr className='ComponentPage-doSectionHr' />
             { this.props.donts }
           </div>
         </div>
@@ -287,4 +343,86 @@ export class ComponentPage extends React.Component<IComponentPageProps, {}> {
 
     return undefined;
   }
+
+  private _editButton(sectionIndex: ComponentPageSection, url?: string): JSX.Element | undefined {
+    if (!url && !this.props.componentUrl) {
+      return undefined;
+    }
+
+    // Get section string for URLs and IDs.
+    const section = ComponentPageSection[sectionIndex];
+    let readableSection = section;
+    const componentName = (this.props.title || this.props.componentName).replace(/\s/g, '');
+
+    // Check if the section contains a function (using PageMarkdown)
+    const {
+      bestPractices,
+      dos,
+      donts,
+      overview,
+    } = this.props;
+    const isMarkdown = {
+      BestPractices: bestPractices ? typeof bestPractices.type === 'function' : false,
+      Dos: dos ? typeof dos.type === 'function' : false,
+      Donts: donts ? typeof donts.type === 'function' : false,
+      Overview: overview ? typeof overview.type === 'function' : false,
+    };
+    let sectionIsMarkdown = false;
+    switch (sectionIndex) {
+      case ComponentPageSection.BestPractices:
+        sectionIsMarkdown = isMarkdown.BestPractices;
+        readableSection = 'Best Practices';
+        break;
+      case ComponentPageSection.Dos:
+        sectionIsMarkdown = isMarkdown.Dos;
+        break;
+      case ComponentPageSection.Donts:
+        sectionIsMarkdown = isMarkdown.Donts;
+        readableSection = 'Don\'ts';
+        break;
+      case ComponentPageSection.Overview:
+        sectionIsMarkdown = isMarkdown.Overview;
+        break;
+      default:
+        sectionIsMarkdown = false;
+        readableSection = section;
+    }
+    if (sectionIsMarkdown === false) {
+      return undefined;
+    }
+
+    // Generate edit URL from componentURL
+    let mdUrl: string | undefined = undefined;
+    if (this.props.componentUrl) {
+      mdUrl = `${this.props.componentUrl}/docs/${componentName}${section}.md`;
+      // Replace /tree/ or /blob/ with /edit/ to get straight to GitHub editor.
+      if (mdUrl!.includes('/tree/')) {
+        mdUrl = mdUrl!.replace('/tree/', '/edit/');
+      } else if (mdUrl!.includes('/blob/')) {
+        mdUrl = mdUrl!.replace('/blob/', '/edit/');
+      }
+    }
+
+    // Allow generated URL fallback.
+    const editUrl = url || mdUrl;
+    if (!editUrl) {
+      return undefined;
+    }
+
+    return (
+      <TooltipHost
+        key={ `${componentName}-${section}-editButton` }
+        content={ `Edit ${componentName} ${readableSection} on GitHub` }
+        id={ `${componentName}-${section}-editButtonHost` }
+      >
+        <IconButton
+          aria-describedby={ `${componentName}-${section}-editButtonHost` }
+          iconProps={ { iconName: 'Edit' } }
+          href={ editUrl }
+          target='_blank'
+          rel='noopener noreferrer'
+        />
+      </TooltipHost>
+    );
+  }
 }

packages/example-app-base/src/index.ts

@@ -1,6 +1,5 @@
 export * from './components/App/App';
 export * from './components/ComponentPage/ComponentPage';
-export * from './components/ComponentPage/ComponentPage';
 export * from './components/ComponentPage/IComponentDemoPageProps';
 export * from './components/ExampleCard/ExampleCard';
 export * from './components/Header/Header';

packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx

@@ -12,10 +12,6 @@ import { ActivityItemBasicExample } from './examples/ActivityItem.Basic.Example'
 import { ActivityItemPersonaExample } from './examples/ActivityItem.Persona.Example';
 import { ActivityItemCompactExample } from './examples/ActivityItem.Compact.Example';
 
-const ActivityItemOverview = require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemOverview.md');
-const ActivityItemDos = require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemDos.md');
-const ActivityItemDonts = require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemDonts.md');
-
 const ActivityItemBasicExampleCode = require('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/examples/ActivityItem.Basic.Example.tsx') as string;
 const ActivityItemPersonaExampleCode = require('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/examples/ActivityItem.Persona.Example.tsx') as string;
 const ActivityItemCompactExampleCode = require('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/examples/ActivityItem.Compact.Example.tsx') as string;
@@ -26,6 +22,7 @@ export class ActivityItemPage extends React.Component<IComponentDemoPageProps, {
       <ComponentPage
         title='ActivityItem'
         componentName='ActivityItem'
+        componentUrl='https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/ActivityItem/'
         exampleCards={
           <div>
             <ExampleCard title='Activity Items with Icons' code={ ActivityItemBasicExampleCode }>
@@ -48,20 +45,20 @@ export class ActivityItemPage extends React.Component<IComponentDemoPageProps, {
         }
         overview={
           <PageMarkdown>
-            { ActivityItemOverview }
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemOverview.md') }
           </PageMarkdown>
         }
         bestPractices={
           <div />
         }
         dos={
           <PageMarkdown>
-            { ActivityItemDos }
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemDos.md') }
           </PageMarkdown>
         }
         donts={
           <PageMarkdown>
-            { ActivityItemDonts }
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/ActivityItem/docs/ActivityItemDonts.md') }
           </PageMarkdown>
         }
         isHeaderVisible={ this.props.isHeaderVisible }