Addressing Issue #531 - Documentation: Components should indicate if they take native props

common/changes/office-ui-fabric-react/documentation-nativeprops_2018-03-08-19-35.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Added documentation for components that allow native props",
+      "type": "minor"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "v-brgarl@microsoft.com"
+}

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

@@ -6,6 +6,7 @@ import {
 import {
   Link
 } from 'office-ui-fabric-react/lib/Link';
+import { MessageBar } from 'office-ui-fabric-react/lib/MessageBar';
 import './ComponentPage.scss';
 
 export interface IComponentPageSection {
@@ -29,6 +30,8 @@ export interface IComponentPageProps {
   className?: string;
   componentStatus?: JSX.Element;
   otherSections?: IComponentPageSection[];
+  allowNativeProps?: boolean | string;
+  nativePropsElement?: string | string[] | undefined;
 }
 
 export class ComponentPage extends React.Component<IComponentPageProps, {}> {
@@ -148,11 +151,43 @@ 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;
+      if (typeof elementString === 'object' && elementString.length > 1) {
+        const elementArr = elementString.slice();
+        for (let _i = 0; _i < elementArr.length; _i++) {
+          if (_i === 0) {
+            elementString = <><code>{ '<' }{ elementArr[_i] }{ '>' }</code></>;
+          } else {
+            elementString = <>{ elementString } and <code>{ '<' }{ elementArr[_i] }{ '>' }</code></>;
+          }
+        }
+        elementString = <>{ elementString } tags</>;
+      } else {
+        elementString = <><code>{ '<' }{ elementString }{ '>' }</code> tag</>;
+      }
+
+      if (typeof this.props.allowNativeProps === 'string') {
+        componentString = <> <code>{ this.props.allowNativeProps }</code></>;
+      }
+
+      return (
+        <MessageBar>
+          <strong>Native Props Allowed{ componentString }</strong> - all HTML attributes native to the { elementString },
+          including all aria and custom data attributes, can be applied as native props on{ componentString || <> this component</> }.
+        </MessageBar>
+      );
+    }
+  }
+
   private _getPropertiesTable(): JSX.Element | undefined {
     if (this.props.propertiesTables) {
       return (
         <div className='ComponentPage-implementationSection'>
           <h2 className='ComponentPage-subHeading' id='Implementation'>Implementation</h2>
+          { this._getNativePropsInfo() }
           { this.props.propertiesTables }
         </div>
       );

packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx

@@ -125,15 +125,14 @@ export class ButtonPage extends React.Component<IComponentDemoPageProps, IButton
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
+        nativePropsElement={ ['a', 'button'] }
         propertiesTables={
-          <div>
-            <PropertiesTableSet
-              sources={ [
-                require<string>('!raw-loader!office-ui-fabric-react/src/components/Button/Button.types.ts')
-              ] }
-            />
-            <p>Besides the above properties, the <code>Button</code> component accepts all properties that the React <code>button</code> and <code>a</code> components accept.</p>
-          </div>
+          <PropertiesTableSet
+            sources={ [
+              require<string>('!raw-loader!office-ui-fabric-react/src/components/Button/Button.types.ts')
+            ] }
+          />
         }
         overview={
           <div>

packages/office-ui-fabric-react/src/components/ChoiceGroup/ChoiceGroupPage.tsx

@@ -39,6 +39,8 @@ export class ChoiceGroupPage extends React.Component<IComponentDemoPageProps, {}
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
+        nativePropsElement={ 'input' }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -88,7 +90,7 @@ export class ChoiceGroupPage extends React.Component<IComponentDemoPageProps, {}
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ChoiceGroupStatus}
+            { ...ChoiceGroupStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/ComboBox/ComboBoxPage.tsx

@@ -29,6 +29,7 @@ export class ComboBoxPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -61,7 +62,7 @@ export class ComboBoxPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ComboBoxStatus}
+            { ...ComboBoxStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Dropdown/DropdownPage.tsx

@@ -45,6 +45,7 @@ export class DropdownPage extends React.Component<IComponentDemoPageProps, {}> {
           </div>
 
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -78,7 +79,7 @@ export class DropdownPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...DropdownStatus}
+            { ...DropdownStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/FocusTrapZone/FocusTrapZonePage.tsx

@@ -42,6 +42,7 @@ export class FocusTrapZonePage extends React.Component<IComponentDemoPageProps,
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [

packages/office-ui-fabric-react/src/components/FocusZone/FocusZonePage.tsx

@@ -37,6 +37,7 @@ export class FocusZonePage extends React.Component<IComponentDemoPageProps, {}>
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [

packages/office-ui-fabric-react/src/components/HoverCard/HoverCardPage.tsx

@@ -32,6 +32,7 @@ export class HoverCardPage extends React.Component<IComponentDemoPageProps, any>
             </ExampleCard>
           </LayerHost>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -47,7 +48,7 @@ export class HoverCardPage extends React.Component<IComponentDemoPageProps, any>
         }
         componentStatus={
           <ComponentStatus
-            {...HoverCardStatus}
+            { ...HoverCardStatus }
           />
         }
         isHeaderVisible={ this.props.isHeaderVisible }

packages/office-ui-fabric-react/src/components/Icon/IconPage.tsx

@@ -39,6 +39,7 @@ export class IconPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -75,7 +76,7 @@ export class IconPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...IconStatus}
+            { ...IconStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Image/ImagePage.tsx

@@ -50,6 +50,8 @@ export class ImagePage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
+        nativePropsElement={ 'img' }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -89,7 +91,7 @@ export class ImagePage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ImageStatus}
+            { ...ImageStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Label/LabelPage.tsx

@@ -22,6 +22,7 @@ export class LabelPage extends React.Component<IComponentDemoPageProps, any> {
             <LabelBasicExample />
           </ExampleCard>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -59,7 +60,7 @@ export class LabelPage extends React.Component<IComponentDemoPageProps, any> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...LabelStatus}
+            { ...LabelStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Link/LinkPage.tsx

@@ -22,6 +22,8 @@ export class LinkPage extends React.Component<IComponentDemoPageProps, {}> {
             <LinkBasicExample />
           </ExampleCard>
         }
+        allowNativeProps={ true }
+        nativePropsElement={ ['a', 'button'] }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -65,7 +67,7 @@ export class LinkPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...LinkStatus}
+            { ...LinkStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/List/ListPage.tsx

@@ -48,6 +48,7 @@ export class ListPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -71,7 +72,7 @@ export class ListPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ListStatus}
+            { ...ListStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Overlay/OverlayPage.tsx

@@ -29,6 +29,7 @@ export class OverlayPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -64,7 +65,7 @@ export class OverlayPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...OverlayStatus}
+            { ...OverlayStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Persona/PersonaPage.tsx

@@ -44,6 +44,7 @@ export class PersonaPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -81,7 +82,7 @@ export class PersonaPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...PersonaStatus}
+            { ...PersonaStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Pivot/PivotPage.tsx

@@ -69,10 +69,12 @@ export class PivotPage extends React.Component<IComponentDemoPageProps, {}> {
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ 'PivotItem' }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
-              require<string>('!raw-loader!office-ui-fabric-react/src/components/Pivot/Pivot.types.ts')
+              require<string>('!raw-loader!office-ui-fabric-react/src/components/Pivot/Pivot.types.ts'),
+              require<string>('!raw-loader!office-ui-fabric-react/src/components/Pivot/PivotItem.types.ts')
             ] }
           />
         }
@@ -118,7 +120,7 @@ export class PivotPage extends React.Component<IComponentDemoPageProps, {}> {
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...PivotStatus}
+            { ...PivotStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/ResizeGroup/ResizeGroupPage.tsx

@@ -10,6 +10,7 @@ import { ResizeGroupOverflowSetExample } from './examples/ResizeGroup.OverflowSe
 import { FlexBoxResizeGroupExample } from './examples/ResizeGroup.FlexBox.Example';
 import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus';
 import { ResizeGroupStatus } from './ResizeGroup.checklist';
+import { MessageBar } from '../../MessageBar';
 
 const ResizeGroupBasicExampleCode = require('!raw-loader!office-ui-fabric-react/src/components/ResizeGroup/examples/ResizeGroup.OverflowSet.Example.tsx') as string;
 
@@ -31,6 +32,7 @@ export class ResizeGroupPage extends React.Component<IComponentDemoPageProps, an
             </ExampleCard>
           </LayerHost>
         }
+        allowNativeProps={ true }
         propertiesTables={
           <PropertiesTableSet
             sources={ [
@@ -103,7 +105,7 @@ export class ResizeGroupPage extends React.Component<IComponentDemoPageProps, an
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ResizeGroupStatus}
+            { ...ResizeGroupStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/ScrollablePane/ScrollablePanePage.tsx

@@ -9,6 +9,7 @@ import { ScrollablePaneDefaultExample } from './examples/ScrollablePane.Default.
 import { ScrollablePaneDetailsListExample } from './examples/ScrollablePane.DetailsList.Example';
 import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus';
 import { ScrollablePaneStatus } from './ScrollablePane.checklist';
+import { MessageBar } from '../../MessageBar';
 
 const ScrollablePaneDefaultExampleCode = require('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/examples/ScrollablePane.Default.Example.tsx') as string;
 
@@ -30,13 +31,17 @@ export class ScrollablePanePage extends React.Component<IComponentDemoPageProps,
             </ExampleCard>
           </div>
         }
+        allowNativeProps={ true }
+        nativePropsElement={ ['a', 'button'] }
         propertiesTables={
-          <PropertiesTableSet
-            sources={ [
-              require<string>('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/ScrollablePane.types.ts'),
-              require<string>('!raw-loader!office-ui-fabric-react/src/components/Sticky/Sticky.types.ts')
-            ] }
-          />
+          <div>
+            <PropertiesTableSet
+              sources={ [
+                require<string>('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/ScrollablePane.types.ts'),
+                require<string>('!raw-loader!office-ui-fabric-react/src/components/Sticky/Sticky.types.ts')
+              ] }
+            />
+          </div>
         }
         overview={
           <div>
@@ -67,7 +72,7 @@ export class ScrollablePanePage extends React.Component<IComponentDemoPageProps,
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...ScrollablePaneStatus}
+            { ...ScrollablePaneStatus }
           />
         }
       />