diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 853c516dad6896..7b8cb59f31cd8b 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -86,7 +86,7 @@ OverflowSet/ @micahgodbolt # Overlay/ # Panel/ # Persona/ -Persona/PersonaCoin.tsx @mtennoe @jakob101 +Persona/PersonaCoin/ @mtennoe @jakob101 Persona/PersonaConsts.tsx @mtennoe @jakob101 pickers/ @joschect # Pivot/ @@ -105,4 +105,59 @@ TeachingBubble/ @micahgodbolt Toggle/ @phkuo Tooltip/ @micahgodbolt +## Docs +# ActivityItem/docs/ +# Breadcrumb/docs/ +# Button/docs/ +Calendar/docs/ @lorejoh12 @sathi23 +Callout/docs/ @joschect +# Check/docs/ +# Checkbox/docs/ +ChoiceGroup/docs/ @srideshpande +# ColorPicker/docs/ +# ComboBox/docs/ +CommandBar/docs/ @micahgodbolt +ContextualMenu/docs/ @joschect +DatePicker/docs/ @lorejoh12 @sathi23 +# DetailsList/docs/ +# Dialog/docs/ +DocumentCard/docs/ @yiminwu @mikewheaton +# Dropdown/docs/ +# Fabric/docs/ +# FacePile/docs/ +# FocusTrapZone/docs/ +# FocusZone/docs/ +GroupedList/docs/ @aditima +HoverCard/docs/ @atneik @Jahnp +# Icon/docs/ +# Image/docs/ +# Label/docs/ +Layer/docs/ @ThomasMichon +# Link/docs/ +List/docs/ @cschleiden +# MarqueeSelection/docs/ +# MessageBar/docs/ +# Modal/docs/ +# Nav/docs/ +OverflowSet/docs/ @micahgodbolt +# Overlay/docs/ +# Panel/docs/ +# Persona/docs/ +pickers/docs/ @joschect +# Pivot/docs/ +# Popup/docs/ +# ProgressIndicator/docs/ +Rating/docs/ @cschleiden +ResizeGroup/docs/ @micahgodbolt +# SearchBox/docs/ +# Slider/docs/ +# SpinButton/docs/ +# Spinner/docs/ +# SwatchColorPicker/docs/ +TeachingBubble/docs/ @micahgodbolt +# TextField/docs/ +# Theme/docs/ +Toggle/docs/ @phkuo +Tooltip/docs/ @micahgodbolt + diff --git a/common/changes/@uifabric/example-app-base/docs-convert-to-markdown_2018-04-16-23-02.json b/common/changes/@uifabric/example-app-base/docs-convert-to-markdown_2018-04-16-23-02.json new file mode 100644 index 00000000000000..b69537a76d71bf --- /dev/null +++ b/common/changes/@uifabric/example-app-base/docs-convert-to-markdown_2018-04-16-23-02.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@uifabric/example-app-base", + "comment": "Fix code block line-height", + "type": "patch" + } + ], + "packageName": "@uifabric/example-app-base", + "email": "v-jojanz@microsoft.com" +} \ No newline at end of file diff --git a/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-14-00-37.json b/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-14-00-37.json new file mode 100644 index 00000000000000..f5af43aba8c7cf --- /dev/null +++ b/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-14-00-37.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@uifabric/styling", + "comment": "Add opt-in @deprecated comments", + "type": "minor" + } + ], + "packageName": "@uifabric/styling", + "email": "jordanjanzen@jordanjanzen.com" +} \ No newline at end of file diff --git a/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-16-23-02.json b/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-16-23-02.json new file mode 100644 index 00000000000000..6ecf9c2f370ccb --- /dev/null +++ b/common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-16-23-02.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@uifabric/styling", + "comment": "Fix deprecated semantic slots returning empty strings", + "type": "patch" + } + ], + "packageName": "@uifabric/styling", + "email": "v-jojanz@microsoft.com" +} \ No newline at end of file diff --git a/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-11-23-54.json b/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-11-23-54.json new file mode 100644 index 00000000000000..b597aadea768ce --- /dev/null +++ b/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-11-23-54.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "office-ui-fabric-react", + "comment": "Convert documentation to markdown for HIG.", + "type": "patch" + } + ], + "packageName": "office-ui-fabric-react", + "email": "v-jojanz@microsoft.com" +} \ No newline at end of file diff --git a/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-14-00-37.json b/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-14-00-37.json new file mode 100644 index 00000000000000..df2e7a1df91faf --- /dev/null +++ b/common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-14-00-37.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "office-ui-fabric-react", + "comment": "Revamp Themes documentation", + "type": "patch" + } + ], + "packageName": "office-ui-fabric-react", + "email": "jordanjanzen@jordanjanzen.com" +} \ No newline at end of file diff --git a/packages/example-app-base/src/components/templates/TypeScriptSnippet.tsx b/packages/example-app-base/src/components/templates/TypeScriptSnippet.tsx index f1257e07fadabb..41f471ca4b88bb 100644 --- a/packages/example-app-base/src/components/templates/TypeScriptSnippet.tsx +++ b/packages/example-app-base/src/components/templates/TypeScriptSnippet.tsx @@ -13,10 +13,11 @@ registerLanguage('typescript', ts); export const rootClass = mergeStyles({ overflowY: 'auto', maxHeight: '400px', + display: 'flex', selectors: { 'code': { fontFamily: 'Monaco, Menlo, Consolas, "Droid Sans Mono", "Inconsolata", "Courier New", monospace', - lineHeight: 19 + lineHeight: '1.6' } } }); @@ -28,7 +29,7 @@ export const lineNumberStyle = { display: 'block', borderRight: '1px solid #666', paddingRight: 4, - lineHeight: '19px' + lineHeight: 'inherit', }; export class TypeScriptSnippet extends React.Component { diff --git a/packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx b/packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx index ad31ba2318ad1f..2f6fb4a34c72cd 100644 --- a/packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx @@ -22,7 +22,7 @@ export class ActivityItemPage extends React.Component diff --git a/packages/office-ui-fabric-react/src/components/Breadcrumb/BreadcrumbPage.tsx b/packages/office-ui-fabric-react/src/components/Breadcrumb/BreadcrumbPage.tsx index ae672f5f559e44..e2331ecdc8533e 100644 --- a/packages/office-ui-fabric-react/src/components/Breadcrumb/BreadcrumbPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Breadcrumb/BreadcrumbPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus'; @@ -24,6 +25,7 @@ export class BreadcrumbPage extends React.Component } overview={ -
-

Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy and help the user understand where they are in relation to the rest of that hierarchy. They also afford one-click access to higher levels of that hierarchy.

-

Breadcrumbs are typically placed, in horizontal form, under the masthead or navigation of an experience, above the primary content area.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Place Breadcrumbs at the top of a page, above a list of items, or above the main content of a page.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md') } + } donts={ -
-
    -
  • Don't use Breadcrumbs as a primary way to navigate an app or site.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md new file mode 100644 index 00000000000000..41d6b2c92cb4ad --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md @@ -0,0 +1 @@ +- Don't use Breadcrumbs as a primary way to navigate an app or site. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md new file mode 100644 index 00000000000000..475b0636fbcd7b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md @@ -0,0 +1 @@ +- Place Breadcrumbs at the top of a page, above a list of items, or above the main content of a page. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md new file mode 100644 index 00000000000000..78bbf512689e34 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md @@ -0,0 +1,3 @@ +Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy and help the user understand where they are in relation to the rest of that hierarchy. They also afford one-click access to higher levels of that hierarchy. + +Breadcrumbs are typically placed, in horizontal form, under the masthead or navigation of an experience, above the primary content area. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx b/packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx index 37e2643a4a00ca..89e84a86343f3a 100644 --- a/packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ButtonStatus } from './Button.checklist'; import { ButtonDefaultExample } from './examples/Button.Default.Example'; @@ -18,7 +19,6 @@ import { ButtonSwapExample } from './examples/Button.Swap.Example'; import { ButtonSplitExample, ButtonSplitCustomExample } from './examples/Button.Split.Example'; import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus'; import { Checkbox } from 'office-ui-fabric-react/lib/Checkbox'; -import { Link } from '../../Link'; import * as exampleStylesImport from '../../common/_exampleStyles.scss'; const exampleStyles: any = exampleStylesImport; @@ -70,8 +70,9 @@ export class ButtonPage extends React.Component } overview={ -
-

Buttons are best used to enable a user to commit a change or complete steps in a task. They are typically found inside forms, dialogs, panels or pages. An example of their usage is confirming the deletion of a file in a confirmation dialog.

-

When considering their place in a layout, contemplate the order in which a user will flow through the UI. As an example, in a form, the individual will need to read and interact with the form fields before submiting the form. Therefore, as a general rule, the button should be placed at the bottom of the UI container (a dialog, panel, or page) which holds the related UI elements.

-

While buttons can technically be used to navigate a user to another part of the experience, this is not recommended unless that navigation is part of an action or their flow.

-

Note that both iconProps and menuIconProps take IIconProps to specify name and type.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Make sure the label conveys a clear purpose of the button to the user.
    • -
  • Button labels must describe the action the button will perform and should include a verb. Use concise, specific, self-explanatory labels, usually a single word.
    • -
  • Buttons should always include a noun if there is any room for interpretation about what the verb operates on.
    • -
  • Consider the affect localization will have on the button and what will happen to components around it.
    • -
  • If the button’s label content is dynamic, consider how the button will resize and what will happen to components around it.
    • -
  • Use only a single line of text in the label of the button.
    • -
  • Expose only one or two buttons to the user at a time, for example, "Accept" and "Cancel". If you need to expose more actions to the user, consider using checkboxes or radio buttons from which the user can select actions, with a single command button to trigger those actions.
    • -
  • Show only one primary button that inherits theme color at rest state. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds.
    • -
  • "Submit", "OK", and "Apply" buttons should always be styled as primary buttons. When "Reset" or "Cancel" buttons appear alongside one of the above, they should be styled as secondary buttons.
    • -
  • Default buttons should always perform safe operations. For example, a default button should never delete.
    • -
  • Use task buttons to cause actions that complete a task or cause a transitional task. Do not use buttons to toggle other UX in the same context. For example, a button may be used to open an interface area but should not be used to open an additional set of components in the same interface.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonDos.md') } + } donts={ -
-
    -
  • Don't use generic labels like "Ok," especially in the case of an error; errors are never "Ok."
    • -
  • Don’t place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (i.e. "Save") or cancels the action (i.e. "Cancel").
    • -
  • Don’t use a button to navigate to another place, use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used.
    • -
  • Don’t put too much text in a button - try to keep the length of your text to a minimum.
    • -
  • Don't put anything other than text in a button.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md new file mode 100644 index 00000000000000..28f24d35ced712 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md @@ -0,0 +1,5 @@ +- Don't use generic labels like "Ok," especially in the case of an error; errors are never "Ok." +- Don’t place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (i.e. "Save") or cancels the action (i.e. "Cancel"). +- Don’t use a button to navigate to another place, use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used. +- Don’t put too much text in a button - try to keep the length of your text to a minimum. +- Don't put anything other than text in a button. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDos.md b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDos.md new file mode 100644 index 00000000000000..e6ad43b773a408 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonDos.md @@ -0,0 +1,11 @@ +- Make sure the label conveys a clear purpose of the button to the user. +- Button labels must describe the action the button will perform and should include a verb. Use concise, specific, self-explanatory labels, usually a single word. +- Buttons should always include a noun if there is any room for interpretation about what the verb operates on. +- Consider the affect localization will have on the button and what will happen to components around it. +- If the button’s label content is dynamic, consider how the button will resize and what will happen to components around it. +- Use only a single line of text in the label of the button. +- Expose only one or two buttons to the user at a time, for example, "Accept" and "Cancel". If you need to expose more actions to the user, consider using checkboxes or radio buttons from which the user can select actions, with a single command button to trigger those actions. +- Show only one primary button that inherits theme color at rest state. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds. +- "Submit", "OK", and "Apply" buttons should always be styled as primary buttons. When "Reset" or "Cancel" buttons appear alongside one of the above, they should be styled as secondary buttons. +- Default buttons should always perform safe operations. For example, a default button should never delete. +- Use task buttons to cause actions that complete a task or cause a transitional task. Do not use buttons to toggle other UX in the same context. For example, a button may be used to open an interface area but should not be used to open an additional set of components in the same interface. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md new file mode 100644 index 00000000000000..07e7c69b1a6868 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md @@ -0,0 +1,7 @@ +Buttons are best used to enable a user to commit a change or complete steps in a task. They are typically found inside forms, dialogs, panels or pages. An example of their usage is confirming the deletion of a file in a confirmation dialog. + +When considering their place in a layout, contemplate the order in which a user will flow through the UI. As an example, in a form, the individual will need to read and interact with the form fields before submiting the form. Therefore, as a general rule, the button should be placed at the bottom of the UI container (a dialog, panel, or page) which holds the related UI elements. + +While buttons can technically be used to navigate a user to another part of the experience, this is not recommended unless that navigation is part of an action or their flow. + +Note that both iconProps and menuIconProps take IIconProps to specify name and type. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Button/examples/Button.Icon.Example.tsx b/packages/office-ui-fabric-react/src/components/Button/examples/Button.Icon.Example.tsx index bcd33745f2ad7e..02ec95de01f36e 100644 --- a/packages/office-ui-fabric-react/src/components/Button/examples/Button.Icon.Example.tsx +++ b/packages/office-ui-fabric-react/src/components/Button/examples/Button.Icon.Example.tsx @@ -23,6 +23,7 @@ export class ButtonIconExample extends React.Component { title='Emoji' ariaLabel='Emoji' /> +

For a list of Icons, visit our Icon documentation.

); } diff --git a/packages/office-ui-fabric-react/src/components/Calendar/CalendarPage.tsx b/packages/office-ui-fabric-react/src/components/Calendar/CalendarPage.tsx index b3609024692755..3ceb6f92b25eaf 100644 --- a/packages/office-ui-fabric-react/src/components/Calendar/CalendarPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Calendar/CalendarPage.tsx @@ -3,7 +3,8 @@ import { ComponentPage, ExampleCard, IComponentDemoPageProps, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { DateRangeType, DayOfWeek } from 'office-ui-fabric-react/lib/Calendar'; import { CalendarButtonExample } from './examples/Calendar.Button.Example'; @@ -20,8 +21,9 @@ export class CalendarPage extends React.Component const today = new Date(Date.now()); return ( @@ -167,40 +169,27 @@ export class CalendarPage extends React.Component /> } overview={ -
-

- The calendar component allows a user to browse through a calendar and pick a date value. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Calendar/docs/CalendarOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use the control as a single entity.
    • -
  • Set the default date to the current date unless a specific date is required for context (e.g. the date of the conference).
    • -
  • The control is designed to resize relative to available screen width. Allow it to render in either wide or narrow as appropriate.
    • -
  • When the control is engaged, the Calendar renders as a flyout and has defined widths (300px -narrow and 440px – wide). Plan your UI implementation accordingly.
    • -
  • The control renders date in a specific format. If allowing for manual entry of date, provide helper text in the appropriate format.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Calendar/docs/CalendarDos.md') } + } donts={ -
-
    -
  • Don't attempt to break apart year from month/day selectors. If granularity is required, use the Dropdown control or something similar.
    • -
  • Don't attempt to force resize the control in any way.
    • -
  • Don't force the control to render one mode vs. the other (year or month/day)
    • -
  • The flyout selector is a light dismiss control. Don't modify this behavior in any way.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Calendar/docs/CalendarDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDonts.md b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDonts.md new file mode 100644 index 00000000000000..85f2b8d6247079 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDonts.md @@ -0,0 +1,4 @@ +- Don't attempt to break apart year from month/day selectors. If granularity is required, use the Dropdown control or something similar. +- Don't attempt to force resize the control in any way. +- Don't force the control to render one mode vs. the other (year or month/day) +- The flyout selector is a light dismiss control. Don't modify this behavior in any way. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDos.md b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDos.md new file mode 100644 index 00000000000000..1ce606e7118c01 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarDos.md @@ -0,0 +1,5 @@ +- Use the control as a single entity. +- Set the default date to the current date unless a specific date is required for context (e.g. the date of the conference). +- The control is designed to resize relative to available screen width. Allow it to render in either wide or narrow as appropriate. +- When the control is engaged, the Calendar renders as a flyout and has defined widths (300px -narrow and 440px – wide). Plan your UI implementation accordingly. +- The control renders date in a specific format. If allowing for manual entry of date, provide helper text in the appropriate format. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarOverview.md b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarOverview.md new file mode 100644 index 00000000000000..9cf4fbf40ffa9f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Calendar/docs/CalendarOverview.md @@ -0,0 +1 @@ +The calendar component allows a user to browse through a calendar and pick a date value. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Callout/CalloutPage.tsx b/packages/office-ui-fabric-react/src/components/Callout/CalloutPage.tsx index 1ad35f6e42f521..6144c446558794 100644 --- a/packages/office-ui-fabric-react/src/components/Callout/CalloutPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Callout/CalloutPage.tsx @@ -3,7 +3,8 @@ import { ComponentPage, ExampleCard, IComponentDemoPageProps, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { items } from '../CommandBar/examples/data'; @@ -25,8 +26,9 @@ export class CalloutPage extends React.Component { return ( @@ -54,47 +56,27 @@ export class CalloutPage extends React.Component {
} overview={ -
-

Callouts are a powerful way to simplify a user interface. They host tips and other information users need when they need it, with minimal effort on their part. Callouts can help you use screen space more effectively and reduce screen clutter. However, poorly designed Callouts can be annoying, distracting, unhelpful, overwhelming, or in the way.

- -

Use a Callout for displaying additional contextual information about an item on the screen. Callouts also have a tail that identifies their source. A common use for Callout is the introduction of a new feature or capability of an app or site. Alternate usages include pairing the Callout with a button or clickable element for on-demand presentation of additional or supporting content.

- -

Real-world examples of this implementation can be seen in administrative interfaces where a particularly difficult-to-understand concept is paired with the iconClassNames.info "i" icon. In this example, Callout - with its tip text - is opened when the user clicks on or hovers over the icon.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Callout/docs/CalloutOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use Callouts to introduce new concepts in an experience where highlighting specific pieces of the UI is necessary.
    • -
  • Do be concise with the information you provide inside of a Callout. Short sentences or sentence fragments are best.
    • -
  • Do be helpful with the tip text inside of your Callout.
    • -
  • Do limit the information inside of a Callout to supplemental information that users don't have to read.
    • -
  • Callouts should be placed near the object being described, usually at the pointer's tail or head if possible.
    • -
  • When additional context - or more advanced description - is necessary, consider placing a link to "Learn more" at the bottom of the Callout and opening the additional content in a new window or Panel when clicked.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Callout/docs/CalloutDos.md') } + } donts={ -
-
    -
  • Don’t overuse Callout without putting the user in control. Too many Callouts which open automatically can be perceived as interrupting workflow and are a bad user experience.
    • -
  • Don't use large, unformatted blocks of text in your Callout, they are difficult to read and overwhelming.
    • -
  • Don't put obvious tip text, or text that simply repeats what is already on the screen in your Callout.
    • -
  • Because the content inside of a Callout isn't always visible, don't put important or required information in a Callout.
    • -
  • Don’t block important UI with the placement of your Callout, it is a poor user experience that will lead to frustration.
    • -
  • Don’t open Callout from within another Callout.
    • -
  • Don’t use Callout to ask the user to confirm an action, use a Dialog instead.
    • -
  • Don’t show Callouts on hidden elements.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Callout/docs/CalloutDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDonts.md b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDonts.md new file mode 100644 index 00000000000000..6520cbea8d16c0 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDonts.md @@ -0,0 +1,8 @@ +- Don’t overuse Callout without putting the user in control. Too many Callouts which open automatically can be perceived as interrupting workflow and are a bad user experience. +- Don't use large, unformatted blocks of text in your Callout, they are difficult to read and overwhelming. +- Don't put obvious tip text, or text that simply repeats what is already on the screen in your Callout. +- Because the content inside of a Callout isn't always visible, don't put important or required information in a Callout. +- Don’t block important UI with the placement of your Callout, it is a poor user experience that will lead to frustration. +- Don’t open Callout from within another Callout. +- Don’t use Callout to ask the user to confirm an action, use a Dialog instead. +- Don’t show Callouts on hidden elements. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDos.md b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDos.md new file mode 100644 index 00000000000000..865bc50ab5309b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutDos.md @@ -0,0 +1,6 @@ +- Use Callouts to introduce new concepts in an experience where highlighting specific pieces of the UI is necessary. +- Do be concise with the information you provide inside of a Callout. Short sentences or sentence fragments are best. +- Do be helpful with the tip text inside of your Callout. +- Do limit the information inside of a Callout to supplemental information that users don't have to read. +- Callouts should be placed near the object being described, usually at the pointer's tail or head if possible. +- When additional context - or more advanced description - is necessary, consider placing a link to "Learn more" at the bottom of the Callout and opening the additional content in a new window or Panel when clicked. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutOverview.md b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutOverview.md new file mode 100644 index 00000000000000..87e096317a2b53 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Callout/docs/CalloutOverview.md @@ -0,0 +1,5 @@ +Callouts are a powerful way to simplify a user interface. They host tips and other information users need when they need it, with minimal effort on their part. Callouts can help you use screen space more effectively and reduce screen clutter. However, poorly designed Callouts can be annoying, distracting, unhelpful, overwhelming, or in the way. + +Use a Callout for displaying additional contextual information about an item on the screen. Callouts also have a tail that identifies their source. A common use for Callout is the introduction of a new feature or capability of an app or site. Alternate usages include pairing the Callout with a button or clickable element for on-demand presentation of additional or supporting content. + +Real-world examples of this implementation can be seen in administrative interfaces where a particularly difficult-to-understand concept is paired with the iconClassNames.info "i" icon. In this example, Callout - with its tip text - is opened when the user clicks on or hovers over the icon. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Checkbox/CheckboxPage.tsx b/packages/office-ui-fabric-react/src/components/Checkbox/CheckboxPage.tsx index dad989bd8097fd..e67cde07ec413f 100644 --- a/packages/office-ui-fabric-react/src/components/Checkbox/CheckboxPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Checkbox/CheckboxPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { CheckboxBasicExample } from './examples/Checkbox.Basic.Example'; import { CheckboxImplementationExamples } from './examples/Checkbox.ImplementationExamples'; @@ -17,8 +18,9 @@ export class CheckboxPage extends React.Component public render() { return ( /> } overview={ -
-

- A Checkbox is a UI element that allows users to switch between two mutually exclusive options (checked or unchecked, on or off) through a single click or tap. It can also be used to indicate a subordinate setting or preference when paired with another control. -

- -

- A Checkbox is used to select or deselect action items. It can be used for a single item or for a list of multiple items that a user can choose from. The control has two selection states: unselected and selected. -

- -

- Use a single Checkbox for a subordinate setting, such as with a "Remember me?" login scenario or with a terms of service agreement. -

- -

- For a binary choice, the main difference between a Checkbox and a toggle switch is that the Checkbox is for status and the toggle switch is for action. You can delay committing a Checkbox interaction (as part of a form submit, for example), while you should immediately commit a toggle switch interaction. Also, only Checkboxes allow for multi-selection. -

- -

- Use multiple Checkboxes for multi-select scenarios in which a user chooses one or more items from a group of choices that are not mutually exclusive. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Checkbox/docs/CheckboxOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Allow users to choose any combination of options when several Checkboxes are grouped together.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDos.md') } + } donts={ -
-
    -
  • Don't use a Checkbox as an on/off control. Instead use a toggle switch.
    • -
  • Don’t use a Checkbox when the user can choose only one option from the group, use radio buttons instead.
    • -
  • Don't put two groups of Checkboxes next to each other. Separate the two groups with labels.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDonts.md b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDonts.md new file mode 100644 index 00000000000000..e99215b63aee3d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDonts.md @@ -0,0 +1,3 @@ +- Don't use a Checkbox as an on/off control. Instead use a toggle switch. +- Don’t use a Checkbox when the user can choose only one option from the group, use radio buttons instead. +- Don't put two groups of Checkboxes next to each other. Separate the two groups with labels. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDos.md b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDos.md new file mode 100644 index 00000000000000..8d33482977d339 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxDos.md @@ -0,0 +1 @@ +- Allow users to choose any combination of options when several Checkboxes are grouped together. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxOverview.md b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxOverview.md new file mode 100644 index 00000000000000..74e2b405f59c81 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Checkbox/docs/CheckboxOverview.md @@ -0,0 +1,9 @@ +A Checkbox is a UI element that allows users to switch between two mutually exclusive options (checked or unchecked, on or off) through a single click or tap. It can also be used to indicate a subordinate setting or preference when paired with another control. + +A Checkbox is used to select or deselect action items. It can be used for a single item or for a list of multiple items that a user can choose from. The control has two selection states: unselected and selected. + +Use a single Checkbox for a subordinate setting, such as with a "Remember me?" login scenario or with a terms of service agreement. + +For a binary choice, the main difference between a Checkbox and a toggle switch is that the Checkbox is for status and the toggle switch is for action. You can delay committing a Checkbox interaction (as part of a form submit, for example), while you should immediately commit a toggle switch interaction. Also, only Checkboxes allow for multi-selection. + +Use multiple Checkboxes for multi-select scenarios in which a user chooses one or more items from a group of choices that are not mutually exclusive. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ChoiceGroup/ChoiceGroupPage.tsx b/packages/office-ui-fabric-react/src/components/ChoiceGroup/ChoiceGroupPage.tsx index d1c26163ae1215..798775ff1eb486 100644 --- a/packages/office-ui-fabric-react/src/components/ChoiceGroup/ChoiceGroupPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ChoiceGroup/ChoiceGroupPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ChoiceGroupBasicExample } from './examples/ChoiceGroup.Basic.Example'; import { ChoiceGroupCustomExample } from './examples/ChoiceGroup.Custom.Example'; @@ -21,8 +22,9 @@ export class ChoiceGroupPage extends React.Component @@ -49,43 +51,22 @@ export class ChoiceGroupPage extends React.Component } overview={ -
-

- The ChoiceGroup component, also known as radio buttons, let users select one option from two or more choices. Each option is represented by one ChoiceGroup button; a user can select only one ChoiceGroup in a button group. -

- -

- ChoiceGroup emphasize all options equally, and that may draw more attention to the options than necessary. Consider using other controls, unless the options deserve extra attention from the user. For example, if the default option is recommended for most users in most situations, use a Dropdown component instead. -

- -

- If there are only two mutually exclusive options, combine them into a single Checkbox or Toggle switch. For example, use a Checkbox for "I agree" instead of ChoiceGroup buttons for "I agree" and "I don't agree." -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use when there are 2-7 options, if you have enough screen space and the options are important enough to be a good use of that screen space. Otherwise, use a Checkbox or Dropdown list.
    • -
  • Use on wizard pages to make the alternatives clear, even if a Checkbox is otherwise acceptable.
    • -
  • List the options in a logical order, such as most likely to be selected to least, simplest operation to most complex, or least risk to most. Alphabetical ordering is not recommended because it is language dependent and therefore not localizable.
    • -
  • If none of the options is a valid choice, add another option to reflect this choice, such as "None" or "Does not apply".
    • -
  • Select the safest (to prevent loss of data or system access) and most secure and private option as the default. If safety and security aren't factors, select the most likely or convenient option.
    • -
  • Align radio buttons vertically instead of horizontally, if possible. Horizontal alignment is harder to read and localize.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDos.md') } + } donts={ -
-
    -
  • Use when the options are numbers that have fixed steps, like 10, 20, 30. Use a Slider component instead.
    • -
  • Use if there are more than 7 options, use a Dropdown instead.
    • -
  • Nest with other ChoiceGroup or CheckBoxes. If possible, keep all the options at the same level.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDonts.md b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDonts.md new file mode 100644 index 00000000000000..7378ea3aeab40e --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDonts.md @@ -0,0 +1,3 @@ +- Use when the options are numbers that have fixed steps, like 10, 20, 30. Use a Slider component instead. +- Use if there are more than 7 options, use a Dropdown instead. +- Nest with other ChoiceGroup or CheckBoxes. If possible, keep all the options at the same level. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDos.md b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDos.md new file mode 100644 index 00000000000000..1d665916a1165b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupDos.md @@ -0,0 +1,6 @@ +- Use when there are 2-7 options, if you have enough screen space and the options are important enough to be a good use of that screen space. Otherwise, use a Checkbox or Dropdown list. +- Use on wizard pages to make the alternatives clear, even if a Checkbox is otherwise acceptable. +- List the options in a logical order, such as most likely to be selected to least, simplest operation to most complex, or least risk to most. Alphabetical ordering is not recommended because it is language dependent and therefore not localizable. +- If none of the options is a valid choice, add another option to reflect this choice, such as "None" or "Does not apply". +- Select the safest (to prevent loss of data or system access) and most secure and private option as the default. If safety and security aren't factors, select the most likely or convenient option. +- Align radio buttons vertically instead of horizontally, if possible. Horizontal alignment is harder to read and localize. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupOverview.md b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupOverview.md new file mode 100644 index 00000000000000..5a1e8d0e3bf9b5 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ChoiceGroup/docs/ChoiceGroupOverview.md @@ -0,0 +1,5 @@ +The ChoiceGroup component, also known as radio buttons, let users select one option from two or more choices. Each option is represented by one ChoiceGroup button; a user can select only one ChoiceGroup in a button group. + +ChoiceGroup emphasize all options equally, and that may draw more attention to the options than necessary. Consider using other controls, unless the options deserve extra attention from the user. For example, if the default option is recommended for most users in most situations, use a Dropdown component instead. + +If there are only two mutually exclusive options, combine them into a single Checkbox or Toggle switch. For example, use a Checkbox for "I agree" instead of ChoiceGroup buttons for "I agree" and "I don't agree." diff --git a/packages/office-ui-fabric-react/src/components/Coachmark/CoachmarkPage.tsx b/packages/office-ui-fabric-react/src/components/Coachmark/CoachmarkPage.tsx index 458642ae39327c..7be1558913add9 100644 --- a/packages/office-ui-fabric-react/src/components/Coachmark/CoachmarkPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Coachmark/CoachmarkPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { CoachmarkBasicExample } from './examples/Coachmark.Basic.Example'; @@ -16,6 +17,7 @@ export class CoachmarkPage extends React.Component @@ -31,35 +33,22 @@ export class CoachmarkPage extends React.Component /> } overview={ -
-

Coachmarks are used to draw a persons attention to a part of the UI, and increase engagement with that element - in the product.

- -

- They should be contextual whenever possible, or related to something that will make existing user flows more efficient -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Only one coachmark + callout combo will be displayed at a time
    • -
  • Coachmarks can be stand alone or sequential. Sequential coachmarks should be used sparingly, to walk through complex - multi-step interactions. It is recommended that a sequence of coachmakrs does not exceed 3 steps.
    • -
  • Coachmarks are designed to only hold Callouts.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDos.md') } + } donts={ -
-
    -
  • Coachmark size, color, and animation should not be altered.
    • -
  • Don't show the coachmark more than once even if the user has not completed the action.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } /> diff --git a/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDonts.md b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDonts.md new file mode 100644 index 00000000000000..8e3f583b0ce98f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDonts.md @@ -0,0 +1,2 @@ +- Coachmark size, color, and animation should not be altered. +- Don't show the coachmark more than once even if the user has not completed the action. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDos.md b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDos.md new file mode 100644 index 00000000000000..e633c88b6505b0 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkDos.md @@ -0,0 +1,3 @@ +- Only one coachmark + callout combo will be displayed at a time +- Coachmarks can be stand alone or sequential. Sequential coachmarks should be used sparingly, to walk through complex multi-step interactions. It is recommended that a sequence of coachmakrs does not exceed 3 steps. +- Coachmarks are designed to only hold Callouts. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkOverview.md b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkOverview.md new file mode 100644 index 00000000000000..c498d3cc459ceb --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Coachmark/docs/CoachmarkOverview.md @@ -0,0 +1,4 @@ +Coachmarks are used to draw a persons attention to a part of the UI, and increase engagement with that element +in the product. + +They should be contextual whenever possible, or related to something that will make existing user flows more efficient diff --git a/packages/office-ui-fabric-react/src/components/ColorPicker/ColorPickerPage.tsx b/packages/office-ui-fabric-react/src/components/ColorPicker/ColorPickerPage.tsx index f03942c79b580f..5ef55148eb49de 100644 --- a/packages/office-ui-fabric-react/src/components/ColorPicker/ColorPickerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ColorPicker/ColorPickerPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ColorPickerBasicExample } from './examples/ColorPicker.Basic.Example'; import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus'; @@ -17,6 +18,7 @@ export class ColorPickerPage extends React.Component } overview={ -
ColorPicker is used to allow a user to select a color
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ColorPicker/docs/ColorPickerOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/ColorPicker/docs/ColorPickerOverview.md b/packages/office-ui-fabric-react/src/components/ColorPicker/docs/ColorPickerOverview.md new file mode 100644 index 00000000000000..1bb98d4569d95c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ColorPicker/docs/ColorPickerOverview.md @@ -0,0 +1 @@ +ColorPicker is used to allow a user to select a color. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ComboBox/ComboBoxPage.tsx b/packages/office-ui-fabric-react/src/components/ComboBox/ComboBoxPage.tsx index 5ef42f2043090c..4417240e41de04 100644 --- a/packages/office-ui-fabric-react/src/components/ComboBox/ComboBoxPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ComboBox/ComboBoxPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ComboBoxBasicExample } from './examples/ComboBox.Basic.Example'; import { ComboBoxCustomStyledExample } from './examples/ComboBox.CustomStyled.Example'; @@ -19,6 +20,7 @@ export class ComboBoxPage extends React.Component { @@ -38,26 +40,22 @@ export class ComboBoxPage extends React.Component { /> } overview={ -
-

- A ComboBox is a list in which the selected item is always visible, and the others are visible on demand by clicking a drop-down button or by typing in the input (unless allowFreeform and autoComplete are both false). They are used to simplify the design and make a choice within the UI. When closed, only the selected item is visible. When users click the drop-down button, all the options become visible. To change the value, users open the list and click another value or use the arrow keys (up and down) to select a new value. When collapsed if autoComplete and/or allowFreeform are true, the user can select a new value by typing. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a ComboBox when there are multiple choices that can be collapsed under one title. Or if the list of items is long or when space is constrained.
    • -
  • ComboBoxs contain shortened statements or words.
    • -
  • Use a ComboBox when the selected option is more important than the alternatives (in contrast to radio buttons where all the choices are visible putting more emphasis on the other options).
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDos.md') } + } donts={ -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDonts.md b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDonts.md new file mode 100644 index 00000000000000..a36e5f39639a4d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDonts.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDos.md b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDos.md new file mode 100644 index 00000000000000..f610e8facabd7d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxDos.md @@ -0,0 +1,3 @@ +- Use a ComboBox when there are multiple choices that can be collapsed under one title. Or if the list of items is long or when space is constrained. +- ComboBoxs contain shortened statements or words. +- Use a ComboBox when the selected option is more important than the alternatives (in contrast to radio buttons where all the choices are visible putting more emphasis on the other options). \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxOverview.md b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxOverview.md new file mode 100644 index 00000000000000..447c617239e24f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ComboBox/docs/ComboBoxOverview.md @@ -0,0 +1 @@ +A ComboBox is a list in which the selected item is always visible, and the others are visible on demand by clicking a drop-down button or by typing in the input (unless allowFreeform and autoComplete are both false). They are used to simplify the design and make a choice within the UI. When closed, only the selected item is visible. When users click the drop-down button, all the options become visible. To change the value, users open the list and click another value or use the arrow keys (up and down) to select a new value. When collapsed if autoComplete and/or allowFreeform are true, the user can select a new value by typing. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/CommandBar/CommandBarPage.tsx b/packages/office-ui-fabric-react/src/components/CommandBar/CommandBarPage.tsx index e8ec7b2d848022..c9a6b62c966e9e 100644 --- a/packages/office-ui-fabric-react/src/components/CommandBar/CommandBarPage.tsx +++ b/packages/office-ui-fabric-react/src/components/CommandBar/CommandBarPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { items, overflowItems, farItems } from './examples/data'; import { CommandBarBasicExample } from './examples/CommandBar.Basic.Example'; @@ -22,12 +23,13 @@ export class CommandBarPage extends React.Component return ( - + @@ -46,45 +48,27 @@ export class CommandBarPage extends React.Component /> } overview={ -
-

- CommandBar is a surface that houses commands that operate on the content of the window, panel, or parent region it resides above. They are one of the most visible and recognizable ways to surface commands, and can be an intuitive method for interacting with content on the page. However, if overloaded or poorly organized, they can be difficult to use and hide valuable commands from your user. CommandBars can also display a search box for finding content; hold simple commands as well as menus; and display the status of ongoing actions. -

-

- Commands should be sorted in order of importance, from left to right or right to left depending on the culture. Secondarily, organize commands in logical groupings for easier recall. CommandBars work best when they display no more than 5-7 commands. This helps users quickly find your most valuable features. If you need to show more commands, consider using the overflow menu. If you need to render status, or viewing controls, these go on the right side of the CommandBar (or left side if in a left to right experience). Do not display more than 2-3 items on the right side as it will make the overall CommandBar difficult to parse. -

-

- All command items should have an icon and a label. Commands can render as labels only as well. In smaller widths, commands can just use icon only, but only for the most recognizable and frequently used commands. All other commands should go into an overflow where text labels can be shown. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/CommandBar/docs/CommandBarOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Sort commands in order of importance from left to right or right to left depending on the culture.
    • -
  • Organize commands into logical groupings.
    • -
  • Display no more than 5-7 commands.
    • -
  • Use overflow to house less frequently-used commands.
    • -
  • In small breakpoints, only have the most recognizable commands render as icon only.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDos.md') } + } donts={ -
-
    -
  • Fill the command bar completely from left to right.
    • -
  • Use icons only for commands in larger widths.
    • -
  • Display more than 2-3 items on the right side of the bar (or left side in left to right experiences).
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDonts.md b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDonts.md new file mode 100644 index 00000000000000..f955732f340005 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDonts.md @@ -0,0 +1,3 @@ +- Fill the command bar completely from left to right. +- Use icons only for commands in larger widths. +- Display more than 2-3 items on the right side of the bar (or left side in left to right experiences). \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDos.md b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDos.md new file mode 100644 index 00000000000000..d78a921b03f729 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarDos.md @@ -0,0 +1,5 @@ +- Sort commands in order of importance from left to right or right to left depending on the culture. +- Organize commands into logical groupings. +- Display no more than 5-7 commands. +- Use overflow to house less frequently-used commands. +- In small breakpoints, only have the most recognizable commands render as icon only. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarOverview.md b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarOverview.md new file mode 100644 index 00000000000000..7ee4004822b8f8 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/CommandBar/docs/CommandBarOverview.md @@ -0,0 +1,5 @@ +CommandBar is a surface that houses commands that operate on the content of the window, panel, or parent region it resides above. They are one of the most visible and recognizable ways to surface commands, and can be an intuitive method for interacting with content on the page. However, if overloaded or poorly organized, they can be difficult to use and hide valuable commands from your user. CommandBars can also display a search box for finding content; hold simple commands as well as menus; and display the status of ongoing actions. + +Commands should be sorted in order of importance, from left to right or right to left depending on the culture. Secondarily, organize commands in logical groupings for easier recall. CommandBars work best when they display no more than 5-7 commands. This helps users quickly find your most valuable features. If you need to show more commands, consider using the overflow menu. If you need to render status, or viewing controls, these go on the right side of the CommandBar (or left side if in a left to right experience). Do not display more than 2-3 items on the right side as it will make the overall CommandBar difficult to parse. + +All command items should have an icon and a label. Commands can render as labels only as well. In smaller widths, commands can just use icon only, but only for the most recognizable and frequently used commands. All other commands should go into an overflow where text labels can be shown. diff --git a/packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuPage.tsx b/packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuPage.tsx index eee454bb403db5..93b82caa1e7cb7 100644 --- a/packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { ContextualMenuBasicExample } from './examples/ContextualMenu.Basic.Example'; import { ContextualMenuIconExample } from './examples/ContextualMenu.Icon.Example'; @@ -35,6 +36,7 @@ export class ContextualMenuPage extends React.Component } overview={ -
-

- ContextualMenus are lists of commands that are based on the context of selection, mouse hover or keyboard focus. They are one of the most effective and highly used command surfaces, and can be used in a variety of places. -

-

- There are variants that originate from a command bar, or from cursor or focus. Those that come from CommandBars use a beak that is horizontally centered on the button. Ones that come from right click and menu button do not have a beak, but appear to the right and below the cursor. ContextualMenus can have submenus from commands, show selection checks, and icons. -

-

- Organize commands in groups divided by rules. This helps users remember command locations, or find less used commands based on proximity to others. One should also group sets of mutually exclusive or multiple selectable options. Use icons sparingly, for high value commands, and don’t mix icons with selection checks, as it makes parsing commands difficult. Avoid submenus of submenus as they can be difficult to invoke or remember. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use to display commands.
    • -
  • Divide groups of commands with rules.
    • -
  • Use selection checks without icons.
    • -
  • Provide submenus for sets of related commands that aren’t as critical as others.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDos.md') } + } donts={ -
-
    -
  • Use them to display content.
    • -
  • Show commands as one large group.
    • -
  • Mix checks and icons.
    • -
  • Create submenus of submenus.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDonts.md b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDonts.md new file mode 100644 index 00000000000000..20c116b591dcea --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDonts.md @@ -0,0 +1,4 @@ +- Use them to display content. +- Show commands as one large group. +- Mix checks and icons. +- Create submenus of submenus. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDos.md b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDos.md new file mode 100644 index 00000000000000..bd79da4125bfa5 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuDos.md @@ -0,0 +1,4 @@ +- Use to display commands. +- Divide groups of commands with rules. +- Use selection checks without icons. +- Provide submenus for sets of related commands that aren’t as critical as others. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuOverview.md b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuOverview.md new file mode 100644 index 00000000000000..5fe6dc43f8b9a6 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ContextualMenu/docs/ContextualMenuOverview.md @@ -0,0 +1,5 @@ +ContextualMenus are lists of commands that are based on the context of selection, mouse hover or keyboard focus. They are one of the most effective and highly used command surfaces, and can be used in a variety of places. + +There are variants that originate from a command bar, or from cursor or focus. Those that come from CommandBars use a beak that is horizontally centered on the button. Ones that come from right click and menu button do not have a beak, but appear to the right and below the cursor. ContextualMenus can have submenus from commands, show selection checks, and icons. + +Organize commands in groups divided by rules. This helps users remember command locations, or find less used commands based on proximity to others. One should also group sets of mutually exclusive or multiple selectable options. Use icons sparingly, for high value commands, and don’t mix icons with selection checks, as it makes parsing commands difficult. Avoid submenus of submenus as they can be difficult to invoke or remember. diff --git a/packages/office-ui-fabric-react/src/components/DatePicker/DatePickerPage.tsx b/packages/office-ui-fabric-react/src/components/DatePicker/DatePickerPage.tsx index a0fff0cacf66a0..e04da9d32ac49e 100644 --- a/packages/office-ui-fabric-react/src/components/DatePicker/DatePickerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/DatePicker/DatePickerPage.tsx @@ -3,7 +3,8 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, - PropertiesTableSet + PropertiesTableSet, + PageMarkdown, } from '@uifabric/example-app-base'; import { DatePickerBasicExample } from './examples/DatePicker.Basic.Example'; import { DatePickerWeekNumbersExample } from './examples/DatePicker.WeekNumbers.Example'; @@ -29,6 +30,7 @@ export class DatePickerPage extends React.Component @@ -59,40 +61,27 @@ export class DatePickerPage extends React.Component /> } overview={ -
-

- The DatePicker component enables a user to pick a date value. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DatePicker/docs/DatePickerOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use the control as a single entity.
    • -
  • Set the default date to the current date unless a specific date is required for context (e.g. the date of the conference).
    • -
  • The control is designed to resize relative to available screen width. Allow it to render in either wide or narrow as appropriate.
    • -
  • When the control is engaged, the DatePicker renders as a flyout and has defined widths (300px -narrow and 440px – wide). Plan your UI implementation accordingly.
    • -
  • The control renders date in a specific format. If allowing for manual entry of date, provide helper text in the appropriate format.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDos.md') } + } donts={ -
-
    -
  • Don't attempt to break apart year from month/day selectors. If granularity is required, use the Dropdown control or something similar.
    • -
  • Don't attempt to force resize the control in any way.
    • -
  • Don't force the control to render one mode vs. the other (year or month/day)
    • -
  • The flyout selector is a light dismiss control. Don't modify this behavior in any way.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDonts.md b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDonts.md new file mode 100644 index 00000000000000..85f2b8d6247079 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDonts.md @@ -0,0 +1,4 @@ +- Don't attempt to break apart year from month/day selectors. If granularity is required, use the Dropdown control or something similar. +- Don't attempt to force resize the control in any way. +- Don't force the control to render one mode vs. the other (year or month/day) +- The flyout selector is a light dismiss control. Don't modify this behavior in any way. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDos.md b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDos.md new file mode 100644 index 00000000000000..171ad514160e0d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerDos.md @@ -0,0 +1,5 @@ +- Use the control as a single entity. +- Set the default date to the current date unless a specific date is required for context (e.g. the date of the conference). +- The control is designed to resize relative to available screen width. Allow it to render in either wide or narrow as appropriate. +- When the control is engaged, the DatePicker renders as a flyout and has defined widths (300px -narrow and 440px – wide). Plan your UI implementation accordingly. +- The control renders date in a specific format. If allowing for manual entry of date, provide helper text in the appropriate format. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerOverview.md b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerOverview.md new file mode 100644 index 00000000000000..4a3478a0cfe812 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DatePicker/docs/DatePickerOverview.md @@ -0,0 +1 @@ +The DatePicker component enables a user to pick a date value. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DetailsList/DetailsListPage.tsx b/packages/office-ui-fabric-react/src/components/DetailsList/DetailsListPage.tsx index 2dad5a197e3a6c..0f78bf6e5b5b2b 100644 --- a/packages/office-ui-fabric-react/src/components/DetailsList/DetailsListPage.tsx +++ b/packages/office-ui-fabric-react/src/components/DetailsList/DetailsListPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus'; @@ -45,6 +46,7 @@ export class DetailsListPage extends React.Component @@ -87,44 +89,27 @@ export class DetailsListPage extends React.Component } overview={ -
-

- DetailsList is a derivative of the List component. It is a robust way to display an information rich collection of items. It can support powerful ways to aid a user in finding content with sorting, grouping and filtering. Lists are a great way to handle large amounts of content, but poorly designed Lists can be difficult to parse. -

-

- Use a DetailsList when density of information is critical. Lists can support single and multiple selection, as well as drag and drop and marquee selection. They are composed of a column header, which contains the metadata fields which are attached to the list items, and provide the ability to sort, filter and even group the list. List items are composed of selection, icon, and name columns at minimum. One can also include other columns such as Date Modified, or any other metadata field associated with the collection. Place the most important columns from left to right for ease of recall and comparison. -

-

- DetailsList is classically used to display files, but is also used to render custom lists that can be purely metadata. Avoid using file type icon overlays to denote status of a file as it can make the entire icon unclear. Be sure to leave ample width for each column’s data. If there are multiple lines of text in a column, consider the variable row height variant. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DetailsList/docs/DetailsListOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use them to display content.
    • -
  • Provide useful columns of metadata.
    • -
  • Display columns in order of importance left to right or right to left depending on the standards of the culture.
    • -
  • Give columns ample default width to display information.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDos.md') } + } donts={ -
-
    -
  • Use them to display commands or settings.
    • -
  • Overload the view with too many columns that require excessive horizontal scrolling.
    • -
  • Make columns so narrow that it truncates the information in typical cases.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDonts.md b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDonts.md new file mode 100644 index 00000000000000..ed191105f1ba01 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDonts.md @@ -0,0 +1,3 @@ +- Use them to display commands or settings. +- Overload the view with too many columns that require excessive horizontal scrolling. +- Make columns so narrow that it truncates the information in typical cases. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDos.md b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDos.md new file mode 100644 index 00000000000000..6aceae28160a1f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListDos.md @@ -0,0 +1,4 @@ +- Use them to display content. +- Provide useful columns of metadata. +- Display columns in order of importance left to right or right to left depending on the standards of the culture. +- Give columns ample default width to display information. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListOverview.md b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListOverview.md new file mode 100644 index 00000000000000..0cac7623ae5283 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DetailsList/docs/DetailsListOverview.md @@ -0,0 +1,5 @@ +DetailsList is a derivative of the List component. It is a robust way to display an information rich collection of items. It can support powerful ways to aid a user in finding content with sorting, grouping and filtering. Lists are a great way to handle large amounts of content, but poorly designed Lists can be difficult to parse. + +Use a DetailsList when density of information is critical. Lists can support single and multiple selection, as well as drag and drop and marquee selection. They are composed of a column header, which contains the metadata fields which are attached to the list items, and provide the ability to sort, filter and even group the list. List items are composed of selection, icon, and name columns at minimum. One can also include other columns such as Date Modified, or any other metadata field associated with the collection. Place the most important columns from left to right for ease of recall and comparison. + +DetailsList is classically used to display files, but is also used to render custom lists that can be purely metadata. Avoid using file type icon overlays to denote status of a file as it can make the entire icon unclear. Be sure to leave ample width for each column’s data. If there are multiple lines of text in a column, consider the variable row height variant. diff --git a/packages/office-ui-fabric-react/src/components/Dialog/DialogPage.tsx b/packages/office-ui-fabric-react/src/components/Dialog/DialogPage.tsx index a7fd2c7b80515e..fd619d2056bc10 100644 --- a/packages/office-ui-fabric-react/src/components/Dialog/DialogPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Dialog/DialogPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { DialogBasicExample } from './examples/Dialog.Basic.Example'; @@ -21,6 +22,7 @@ export class DialogPage extends React.Component { @@ -48,43 +50,27 @@ export class DialogPage extends React.Component { /> } overview={ -
-

- Dialogs are temporary, modal UI overlay that generally provide contextual app information or require user confirmation/input. In most cases, Dialogs block interactions with the web page or application until being explicitly dismissed, and often request action from the user. They are primarily used for lightweight creation or edit tasks, and simple management tasks. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dialog/docs/DialogOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use Dialogs for quick, actionable interactions, such as making a choice or needing the user to provide information.
    • -
  • When possible, try a non-blocking Dialog before resorting to a blocking Dialog.
    • -
  • Only include information needed to help users make a decision.
    • -
  • Button text should reflect the actions available to the user (e.g. save, delete).
    • -
  • Validate that the user's entries are acceptable before closing the Dialog. Show an inline validation error near the field they must correct.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dialog/docs/DialogDos.md') } + } donts={ -
-
    -
  • Don’t overuse Dialogs. To some extent they can be perceived as interrupting workflow, and too many can be a bad user experience.
    • -
  • Avoid "Are you sure?" or confirmation Dialogs unless the user is making an irreversible or destructive choice.
    • -
  • Do not use a blocking Dialog unless absolutely necessary because they are very disruptive.
    • -
  • Don’t have long sentences or complicated choices.
    • -
  • Avoid generic button labels like "Ok" if you can be more specific about the action a user is about to complete.
    • -
  • Don't dismiss the Dialog if underlying problem is not fixed. Don't put the user back into a broken/error state.
    • -
  • Don't provide the user with more than 3 buttons.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dialog/docs/DialogDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDonts.md b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDonts.md new file mode 100644 index 00000000000000..23820e70744aab --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDonts.md @@ -0,0 +1,7 @@ +- Don’t overuse Dialogs. To some extent they can be perceived as interrupting workflow, and too many can be a bad user experience. +- Avoid "Are you sure?" or confirmation Dialogs unless the user is making an irreversible or destructive choice. +- Do not use a blocking Dialog unless absolutely necessary because they are very disruptive. +- Don’t have long sentences or complicated choices. +- Avoid generic button labels like "Ok" if you can be more specific about the action a user is about to complete. +- Don't dismiss the Dialog if underlying problem is not fixed. Don't put the user back into a broken/error state. +- Don't provide the user with more than 3 buttons. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDos.md b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDos.md new file mode 100644 index 00000000000000..6d594c3a4f855b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogDos.md @@ -0,0 +1,5 @@ +- Use Dialogs for quick, actionable interactions, such as making a choice or needing the user to provide information. +- When possible, try a non-blocking Dialog before resorting to a blocking Dialog. +- Only include information needed to help users make a decision. +- Button text should reflect the actions available to the user (e.g. save, delete). +- Validate that the user's entries are acceptable before closing the Dialog. Show an inline validation error near the field they must correct. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogOverview.md b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogOverview.md new file mode 100644 index 00000000000000..1ab5ac6894b767 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dialog/docs/DialogOverview.md @@ -0,0 +1 @@ +Dialogs are temporary, modal UI overlay that generally provide contextual app information or require user confirmation/input. In most cases, Dialogs block interactions with the web page or application until being explicitly dismissed, and often request action from the user. They are primarily used for lightweight creation or edit tasks, and simple management tasks. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Divider/DividerPage.tsx b/packages/office-ui-fabric-react/src/components/Divider/DividerPage.tsx index 01f777e885cc61..f15ecf73f1a6c8 100644 --- a/packages/office-ui-fabric-react/src/components/Divider/DividerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Divider/DividerPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { VerticalDividerBasicExample } from './examples/VerticalDivider.Basic.Example'; @@ -20,6 +21,7 @@ export class DividerPage extends React.Component { @@ -38,47 +40,30 @@ export class DividerPage extends React.Component { /> } overview={ -
-

- A Divider is a line that is used to visually differentiate different parts of a UI. They are commonly used in headers and command bars. This divider automatically center algins itself within the parent container and can be customized to be shown in different heights and colors. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Divider/docs/DividerOverview.md') } + } bestPractices={ -
-

- Use a divider component to show a sectional or continuity change in the content between two blocks of information. The spacing around the divider is generally determined by the content surrounding it. -

-

- There are two recommended divider color combinations: -

    -
  1. #C8C8C8/neutralTertiaryAlt divider when used within an #F4F4F4/neutralLighter layout
    2. -
  2. #EAEAEA/neutralLight divider when used within an #FFFFFF/white layout
    3. -
-

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Divider/docs/DividerBestPractices.md') } + } dos={ -
-
    -
  • Use a divider to separate sections that may not otherwise have a clear beginning or end.
    • -
  • Use a divider to separate information blocks where the context or continuity changes between the blocks.
    • -
  • When the divider is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type, or may be used to provide for an accessible fallback in older browsers that do not support WAI-ARIA use role="presentation".
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Divider/docs/DividerDos.md') } + } donts={ -
-
    -
  • Do not use dividers for graphic decoration.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Divider/docs/DividerDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Divider/docs/DividerBestPractices.md b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerBestPractices.md new file mode 100644 index 00000000000000..7adf00e231ba11 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerBestPractices.md @@ -0,0 +1,6 @@ +Use a divider component to show a sectional or continuity change in the content between two blocks of information. The spacing around the divider is generally determined by the content surrounding it. + +There are two recommended divider color combinations: + +1. #C8C8C8/neutralTertiaryAlt divider when used within an #F4F4F4/neutralLighter layout +1. #EAEAEA/neutralLight divider when used within an #FFFFFF/white layout \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDonts.md b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDonts.md new file mode 100644 index 00000000000000..93d2dfb5889d07 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDonts.md @@ -0,0 +1 @@ +- Do not use dividers for graphic decoration. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDos.md b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDos.md new file mode 100644 index 00000000000000..a5d8dd0e7a369a --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerDos.md @@ -0,0 +1,3 @@ +- Use a divider to separate sections that may not otherwise have a clear beginning or end. +- Use a divider to separate information blocks where the context or continuity changes between the blocks. +- When the divider is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type, or may be used to provide for an accessible fallback in older browsers that do not support WAI-ARIA use role="presentation". \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Divider/docs/DividerOverview.md b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerOverview.md new file mode 100644 index 00000000000000..556c7e711f1913 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Divider/docs/DividerOverview.md @@ -0,0 +1 @@ +A Divider is a line that is used to visually differentiate different parts of a UI. They are commonly used in headers and command bars. This divider automatically center algins itself within the parent container and can be customized to be shown in different heights and colors. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DocumentCard/DocumentCardPage.tsx b/packages/office-ui-fabric-react/src/components/DocumentCard/DocumentCardPage.tsx index 11dd49b7b1862f..0fd46157f885fd 100644 --- a/packages/office-ui-fabric-react/src/components/DocumentCard/DocumentCardPage.tsx +++ b/packages/office-ui-fabric-react/src/components/DocumentCard/DocumentCardPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { DocumentCardBasicExample } from './examples/DocumentCard.Basic.Example'; @@ -21,6 +22,7 @@ export class DocumentCardPage extends React.Component @@ -54,31 +56,22 @@ export class DocumentCardPage extends React.Component } overview={ -
-

- A DocumentCard is a card representation of a file. This is usually richer than just seeing the file in a grid view, as the card can contain additional metadata or actions. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use this control to represent Office documents or other user-relevant files in aggregate views, such as when you are showing the user’s most trending document.
    • -
  • Incorporate metadata that is relevant and useful in this particular view. A card can be specialized to be about the document’s latest changes, or about the document’s popularity, as you see fit.
    • -
  • Use the DocumentCard when you are illustrating an event that encompasses multiple files. For example, a card can be configured to represent a single upload action that consisted in adding more than one file.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDos.md') } + } donts={ -
-
    -
  • Don’t use the DocumentCard in views where the user is likely to be performing bulk operations in files, or when the list may get very long. Specifically, if you are showing all the items inside an actual folder, a card may be overkill because the majority of the items in the folder may not have interesting metadata.
    • -
  • Don’t use the DocumentCard if space is at a premium or you can’t show relevant and timely commands or metadata. Cards are useful because they can expose on-item interactions like “Share” buttons or view counts. If your app does not need this, show a simple grid or list of items instead, which are easier to scan.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDonts.md b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDonts.md new file mode 100644 index 00000000000000..91e89379f28c2b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDonts.md @@ -0,0 +1,2 @@ +- Don’t use the DocumentCard in views where the user is likely to be performing bulk operations in files, or when the list may get very long. Specifically, if you are showing all the items inside an actual folder, a card may be overkill because the majority of the items in the folder may not have interesting metadata. +- Don’t use the DocumentCard if space is at a premium or you can’t show relevant and timely commands or metadata. Cards are useful because they can expose on-item interactions like “Share” buttons or view counts. If your app does not need this, show a simple grid or list of items instead, which are easier to scan. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDos.md b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDos.md new file mode 100644 index 00000000000000..78f202920bc2be --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardDos.md @@ -0,0 +1,3 @@ +- Use this control to represent Office documents or other user-relevant files in aggregate views, such as when you are showing the user’s most trending document. +- Incorporate metadata that is relevant and useful in this particular view. A card can be specialized to be about the document’s latest changes, or about the document’s popularity, as you see fit. +- Use the DocumentCard when you are illustrating an event that encompasses multiple files. For example, a card can be configured to represent a single upload action that consisted in adding more than one file. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardOverview.md b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardOverview.md new file mode 100644 index 00000000000000..938cdc0ee0b819 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/DocumentCard/docs/DocumentCardOverview.md @@ -0,0 +1 @@ +A DocumentCard is a card representation of a file. This is usually richer than just seeing the file in a grid view, as the card can contain additional metadata or actions. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Dropdown/Dropdown.scss b/packages/office-ui-fabric-react/src/components/Dropdown/Dropdown.scss index 265e0effa99e10..3a59db832b0343 100644 --- a/packages/office-ui-fabric-react/src/components/Dropdown/Dropdown.scss +++ b/packages/office-ui-fabric-react/src/components/Dropdown/Dropdown.scss @@ -34,6 +34,7 @@ $DropDown-item-height: 32px; @include ms-font-m; color: $ms-color-neutralPrimary; + height: $DropDown-height; position: relative; outline: 0; user-select: none; @@ -149,7 +150,7 @@ $DropDown-item-height: 32px; border: 1px solid $ms-color-neutralTertiary; cursor: pointer; display: block; - height: $DropDown-height; + height: 100%; line-height: $DropDown-height - 2px; // height minus the border @include padding(0, $DropDown-height, 0, 12px); position: relative; diff --git a/packages/office-ui-fabric-react/src/components/Dropdown/DropdownPage.tsx b/packages/office-ui-fabric-react/src/components/Dropdown/DropdownPage.tsx index f7ffc94d031b4b..7ee6ef7ef9cf83 100644 --- a/packages/office-ui-fabric-react/src/components/Dropdown/DropdownPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Dropdown/DropdownPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { DropdownBasicExample } from './examples/Dropdown.Basic.Example'; @@ -21,6 +22,7 @@ export class DropdownPage extends React.Component { { /> } overview={ -
-

- A Dropdown is a list in which the selected item is always visible, and the others are visible on demand by clicking a drop-down button. They are used to simplify the design and make a choice within the UI. When closed, only the selected item is visible. When users click the drop-down button, all the options become visible. To change the value, users open the list and click another value or use the arrow keys (up and down) to select a new value. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dropdown/docs/DropdownOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a Dropdown when there are multiple choices that can be collapsed under one title. Or if the list of items is long or when space is constrained.
    • -
  • Dropdowns contain shortened statements or words.
    • -
  • Use a Dropdown when the selected option is more important than the alternatives (in contrast to radio buttons where all the choices are visible putting more emphasis on the other options).
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dropdown/docs/DropdownDos.md') } + } donts={ -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Dropdown/docs/DropdownDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDonts.md b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDonts.md new file mode 100644 index 00000000000000..b08d6752b763d2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDonts.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDos.md b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDos.md new file mode 100644 index 00000000000000..77e8c0749db6bb --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownDos.md @@ -0,0 +1,3 @@ +- Use a Dropdown when there are multiple choices that can be collapsed under one title. Or if the list of items is long or when space is constrained. +- Dropdowns contain shortened statements or words. +- Use a Dropdown when the selected option is more important than the alternatives (in contrast to radio buttons where all the choices are visible putting more emphasis on the other options). \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownOverview.md b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownOverview.md new file mode 100644 index 00000000000000..c88e66c0bce7ec --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Dropdown/docs/DropdownOverview.md @@ -0,0 +1 @@ +A Dropdown is a list in which the selected item is always visible, and the others are visible on demand by clicking a drop-down button. They are used to simplify the design and make a choice within the UI. When closed, only the selected item is visible. When users click the drop-down button, all the options become visible. To change the value, users open the list and click another value or use the arrow keys (up and down) to select a new value. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Facepile/FacepilePage.tsx b/packages/office-ui-fabric-react/src/components/Facepile/FacepilePage.tsx index 816ddf578e3f7f..32ac5930d7640e 100644 --- a/packages/office-ui-fabric-react/src/components/Facepile/FacepilePage.tsx +++ b/packages/office-ui-fabric-react/src/components/Facepile/FacepilePage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { FacepileAddFaceExample } from './examples/Facepile.AddFace.Example'; @@ -22,6 +23,7 @@ export class FacepilePage extends React.Component { @@ -43,65 +45,27 @@ export class FacepilePage extends React.Component { /> } overview={ -
-

- The Facepile shows a list of faces or initials in a horizontal lockup. Each circle represents a person. Many times this component is used when sharing who has access to a specific view or file or when assigning a user to a task within a workflow. -

- -

Adding people

-

- The component can include an add button which can be used for quickly adding a person to the list. -

- -

Empty state

-

- The empty state of the Facepile should include only an add button. Another variant is to use an input field with placeholder text instructing the user to add a person. See the PeoplePicker component for the menu used to add people to the Facepile list. -

- -

One person

-

- When there is only one person in the Facepile, consider using their name next to the face or initials. -

- -

Expanding the list when there is no overflow

- -

- When there is a need to show the Facepile expanded into a vertical list, include a downward chevron button. Clicking or tapping on the chevron would open a standard list view of personas. -

- -

Overflow

- -

- When the Facepile exceeds a max number of 5 people, show a button at the end of the list indicating how many are not being shown. Clicking or tapping on the overflow would open a standard list view of personas. -

- -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Facepile/docs/FacepileOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use if looking for a way to represent who has access to an area and need to show that as a people representation.
    • -
  • Only show the Add button if a user has access to do so.
    • -
  • Allow a way for the user to understand who the person is. Many common ways to do this are with a tooltip or adding the ability to open up a PeopleCard Experience.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Facepile/docs/FacepileDos.md') } + } donts={ -
-
    -
  • Use for things other than people.
    • -
  • Overwhelm users by listing every single person as a circle but truncate and provide a way to see the full list.
    • -
  • Don’t use this control for experiences where you need to manage details of hundreds of users, you are better off using a list control.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Facepile/docs/FacepileDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDonts.md b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDonts.md new file mode 100644 index 00000000000000..3b134de7609698 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDonts.md @@ -0,0 +1,3 @@ +- Use for things other than people. +- Overwhelm users by listing every single person as a circle but truncate and provide a way to see the full list. +- Don’t use this control for experiences where you need to manage details of hundreds of users, you are better off using a list control. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDos.md b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDos.md new file mode 100644 index 00000000000000..450077a4d2a137 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileDos.md @@ -0,0 +1,3 @@ +- Use if looking for a way to represent who has access to an area and need to show that as a people representation. +- Only show the Add button if a user has access to do so. +- Allow a way for the user to understand who the person is. Many common ways to do this are with a tooltip or adding the ability to open up a PeopleCard Experience. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileOverview.md b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileOverview.md new file mode 100644 index 00000000000000..0a6d45d803c7b4 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Facepile/docs/FacepileOverview.md @@ -0,0 +1,21 @@ +The Facepile shows a list of faces or initials in a horizontal lockup. Each circle represents a person. Many times this component is used when sharing who has access to a specific view or file or when assigning a user to a task within a workflow. + +## Adding people + +The component can include an add button which can be used for quickly adding a person to the list. + +## Empty state + +The empty state of the Facepile should include only an add button. Another variant is to use an input field with placeholder text instructing the user to add a person. See the PeoplePicker component for the menu used to add people to the Facepile list. + +## One person + +When there is only one person in the Facepile, consider using their name next to the face or initials. + +## Expanding the list when there is no overflow + +When there is a need to show the Facepile expanded into a vertical list, include a downward chevron button. Clicking or tapping on the chevron would open a standard list view of personas. + +## Overflow + +When the Facepile exceeds a max number of 5 people, show a button at the end of the list indicating how many are not being shown. Clicking or tapping on the overflow would open a standard list view of personas. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/FocusTrapZone/FocusTrapZonePage.tsx b/packages/office-ui-fabric-react/src/components/FocusTrapZone/FocusTrapZonePage.tsx index 3eaa6ec90c340a..849002054b65db 100644 --- a/packages/office-ui-fabric-react/src/components/FocusTrapZone/FocusTrapZonePage.tsx +++ b/packages/office-ui-fabric-react/src/components/FocusTrapZone/FocusTrapZonePage.tsx @@ -6,6 +6,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import FocusTrapZoneBoxExample from './examples/FocusTrapZone.Box.Example'; @@ -26,6 +27,7 @@ export class FocusTrapZonePage extends React.Component @@ -51,10 +53,9 @@ export class FocusTrapZonePage extends React.Component } overview={ -
- FocusTrapZone - is used to trap the focus in any html element. Pressing tab will circle focus within the inner focusable elements of the FocusTrapZone. -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/FocusTrapZone/docs/FocusTrapZoneOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } /> diff --git a/packages/office-ui-fabric-react/src/components/FocusTrapZone/docs/FocusTrapZoneOverview.md b/packages/office-ui-fabric-react/src/components/FocusTrapZone/docs/FocusTrapZoneOverview.md new file mode 100644 index 00000000000000..33b632403e555e --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/FocusTrapZone/docs/FocusTrapZoneOverview.md @@ -0,0 +1 @@ +FocusTrapZone is used to trap the focus in any html element. Pressing tab will circle focus within the inner focusable elements of the FocusTrapZone. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/FocusZone/FocusZonePage.tsx b/packages/office-ui-fabric-react/src/components/FocusZone/FocusZonePage.tsx index 7443be6a2b82c0..76eae2de7ad3a4 100644 --- a/packages/office-ui-fabric-react/src/components/FocusZone/FocusZonePage.tsx +++ b/packages/office-ui-fabric-react/src/components/FocusZone/FocusZonePage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { FocusZonePhotosExample } from './examples/FocusZone.Photos.Example'; @@ -21,6 +22,7 @@ export class FocusZonePage extends React.Component @@ -46,11 +48,9 @@ export class FocusZonePage extends React.Component /> } overview={ -
-

FocusZones abstract arrow key navigation behaviors. Tabbable elements (buttons, anchors, and elements with data-is-focusable='true' attributes) are considered when pressing directional arrow keys and focus is moved appropriately. Tabbing to a zone sets focus only to the current "active" element, making it simple to use the tab key to transition from one zone to the next, rather than through every focusable element.

- -

Using a FocusZone is simple. Just wrap a bunch of content inside of a FocusZone, and arrows and tabbling will be handled for you! See examples below.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/FocusZone/docs/FocusZoneOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } /> diff --git a/packages/office-ui-fabric-react/src/components/FocusZone/docs/FocusZoneOverview.md b/packages/office-ui-fabric-react/src/components/FocusZone/docs/FocusZoneOverview.md new file mode 100644 index 00000000000000..f622f7eafcb24b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/FocusZone/docs/FocusZoneOverview.md @@ -0,0 +1,3 @@ +FocusZones abstract arrow key navigation behaviors. Tabbable elements (buttons, anchors, and elements with data-is-focusable='true' attributes) are considered when pressing directional arrow keys and focus is moved appropriately. Tabbing to a zone sets focus only to the current "active" element, making it simple to use the tab key to transition from one zone to the next, rather than through every focusable element. + +Using a FocusZone is simple. Just wrap a bunch of content inside of a FocusZone, and arrows and tabbling will be handled for you! See examples below. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/GroupedList/GroupedListPage.tsx b/packages/office-ui-fabric-react/src/components/GroupedList/GroupedListPage.tsx index df8228539ddb0a..7df41177b6cce7 100644 --- a/packages/office-ui-fabric-react/src/components/GroupedList/GroupedListPage.tsx +++ b/packages/office-ui-fabric-react/src/components/GroupedList/GroupedListPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { GroupedListBasicExample } from './examples/GroupedList.Basic.Example'; @@ -19,6 +20,7 @@ export class GroupedListPage extends React.Component @@ -37,12 +39,14 @@ export class GroupedListPage extends React.Component } overview={ -

Allows you to render a set of items as multiple lists with various grouping properties.

+ + { require('!raw-loader!office-ui-fabric-react/src/components/GroupedList/docs/GroupedListOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/GroupedList/docs/GroupedListOverview.md b/packages/office-ui-fabric-react/src/components/GroupedList/docs/GroupedListOverview.md new file mode 100644 index 00000000000000..3fe7044a88a779 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/GroupedList/docs/GroupedListOverview.md @@ -0,0 +1 @@ +Allows you to render a set of items as multiple lists with various grouping properties. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/HoverCard/HoverCardPage.tsx b/packages/office-ui-fabric-react/src/components/HoverCard/HoverCardPage.tsx index 20eff65a396328..a518cb1af47000 100644 --- a/packages/office-ui-fabric-react/src/components/HoverCard/HoverCardPage.tsx +++ b/packages/office-ui-fabric-react/src/components/HoverCard/HoverCardPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { HoverCardBasicExample } from './examples/HoverCard.Basic.Example'; @@ -22,6 +23,7 @@ export class HoverCardPage extends React.Component @@ -42,9 +44,9 @@ export class HoverCardPage extends React.Component /> } overview={ -
-

HoverCards supplement content associated with a specific data element.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/HoverCard/docs/HoverCardOverview.md') } + } componentStatus={ { @@ -48,30 +50,22 @@ export class IconPage extends React.Component { /> } overview={ -
-

- In a computer's graphical user interface ( GUI ), an icon is an image that represents an application, a capability, or some other concept or specific entity with meaning for the user. An icon is usually selectable but can also be a nonselectable image such as a company's logo. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Icon/docs/IconOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Adjust to proper size to highlight importance but not occupying too much space.
    • -
  • Be simple and concise.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Icon/docs/IconDos.md') } + } donts={ -
-
    -
  • Use Icons to show pictures.
    • -
  • Use photos or long sentences as icons.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Icon/docs/IconDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Icon/docs/IconDonts.md b/packages/office-ui-fabric-react/src/components/Icon/docs/IconDonts.md new file mode 100644 index 00000000000000..6bd5aeb9603c0f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Icon/docs/IconDonts.md @@ -0,0 +1,2 @@ +- Use Icons to show pictures. +- Use photos or long sentences as icons. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Icon/docs/IconDos.md b/packages/office-ui-fabric-react/src/components/Icon/docs/IconDos.md new file mode 100644 index 00000000000000..6b47d1a010ea1c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Icon/docs/IconDos.md @@ -0,0 +1,2 @@ +- Adjust to proper size to highlight importance but not occupying too much space. +- Be simple and concise. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Icon/docs/IconOverview.md b/packages/office-ui-fabric-react/src/components/Icon/docs/IconOverview.md new file mode 100644 index 00000000000000..3b1789c9c78023 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Icon/docs/IconOverview.md @@ -0,0 +1,3 @@ +In a computer's graphical user interface ( GUI ), an icon is an image that represents an application, a capability, or some other concept or specific entity with meaning for the user. An icon is usually selectable but can also be a nonselectable image such as a company's logo. + +For a list of Icons, visit our Icon documentation. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Image/ImagePage.tsx b/packages/office-ui-fabric-react/src/components/Image/ImagePage.tsx index d09b82965ceb22..61a4c05ed5ddf3 100644 --- a/packages/office-ui-fabric-react/src/components/Image/ImagePage.tsx +++ b/packages/office-ui-fabric-react/src/components/Image/ImagePage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import './ImagePage.scss'; @@ -28,6 +29,7 @@ export class ImagePage extends React.Component { @@ -60,33 +62,22 @@ export class ImagePage extends React.Component { /> } overview={ -
- Images render an image. The borders have been added to these examples in order to help visualize empty space in the image frame. -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Image/docs/ImageOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • - Provide descriptive values for the alt text attribute for all images. - If alt text isn't provided for images, the image information is inaccessible, for example, to people who cannot see and use a screen reader that reads aloud the information on a page. -
      -
    • Consider context. If the image represents a function, be sure to indicate that. If it is to be consumed with other objects on the page, consider that as well.
      • -
    • Make the description brief but accurate. Use one sentence, two at the most.
      • -
    -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Image/docs/ImageDos.md') } + } donts={ -
-
    -
  • Repeat information in your alt text that is already on the page. Don't use "image of" or "graphic of" to describe it, as that is already apparent to the reader.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Image/docs/ImageDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Image/docs/ImageDonts.md b/packages/office-ui-fabric-react/src/components/Image/docs/ImageDonts.md new file mode 100644 index 00000000000000..81f37145e1ee60 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Image/docs/ImageDonts.md @@ -0,0 +1 @@ +- Repeat information in your alt text that is already on the page. Don't use "image of" or "graphic of" to describe it, as that is already apparent to the reader. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Image/docs/ImageDos.md b/packages/office-ui-fabric-react/src/components/Image/docs/ImageDos.md new file mode 100644 index 00000000000000..0a42ddaf626b4b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Image/docs/ImageDos.md @@ -0,0 +1,4 @@ +- Provide descriptive values for the alt text attribute for all images. +If alt text isn't provided for images, the image information is inaccessible, for example, to people who cannot see and use a screen reader that reads aloud the information on a page. + - Consider context. If the image represents a function, be sure to indicate that. If it is to be consumed with other objects on the page, consider that as well. + - Make the description brief but accurate. Use one sentence, two at the most. diff --git a/packages/office-ui-fabric-react/src/components/Image/docs/ImageOverview.md b/packages/office-ui-fabric-react/src/components/Image/docs/ImageOverview.md new file mode 100644 index 00000000000000..33c14c2dd74deb --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Image/docs/ImageOverview.md @@ -0,0 +1 @@ +Images render an image. The borders have been added to these examples in order to help visualize empty space in the image frame. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Label/LabelPage.tsx b/packages/office-ui-fabric-react/src/components/Label/LabelPage.tsx index 0a4a56da9b28e2..4c5b6b079cbcb3 100644 --- a/packages/office-ui-fabric-react/src/components/Label/LabelPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Label/LabelPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { LabelBasicExample } from './examples/Label.Basic.Example'; @@ -17,6 +18,7 @@ export class LabelPage extends React.Component { @@ -31,31 +33,22 @@ export class LabelPage extends React.Component { /> } overview={ -
-

- Labels give a name or title to a component or group of components. Labels should be in close proximity to the component or group they are paired with. Some components, such as TextField, Dropdown, or Toggle, already have Labels incorporated, but other components may optionally add a Label if it helps inform the user of the component’s purpose. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Label/docs/LabelOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use sentence casing, e.g. “First name”.
    • -
  • Be short and concise.
    • -
  • When adding a Label to components, use the text as a noun or short noun phrase.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Label/docs/LabelDos.md') } + } donts={ -
-
    -
  • Use Labels as instructional text, e.g. “Click to get started”.
    • -
  • Don’t use full sentences or complex punctuation (colons, semicolons, etc.).
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Label/docs/LabelDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Label/docs/LabelDonts.md b/packages/office-ui-fabric-react/src/components/Label/docs/LabelDonts.md new file mode 100644 index 00000000000000..33370b8e68f5d0 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Label/docs/LabelDonts.md @@ -0,0 +1,2 @@ +- Use Labels as instructional text, e.g. “Click to get started”. +- Don’t use full sentences or complex punctuation (colons, semicolons, etc.). \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Label/docs/LabelDos.md b/packages/office-ui-fabric-react/src/components/Label/docs/LabelDos.md new file mode 100644 index 00000000000000..7269633705a337 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Label/docs/LabelDos.md @@ -0,0 +1,3 @@ +- Use sentence casing, e.g. “First name”. +- Be short and concise. +- When adding a Label to components, use the text as a noun or short noun phrase. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Label/docs/LabelOverview.md b/packages/office-ui-fabric-react/src/components/Label/docs/LabelOverview.md new file mode 100644 index 00000000000000..7cbdb2ed43e853 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Label/docs/LabelOverview.md @@ -0,0 +1 @@ +Labels give a name or title to a component or group of components. Labels should be in close proximity to the component or group they are paired with. Some components, such as TextField, Dropdown, or Toggle, already have Labels incorporated, but other components may optionally add a Label if it helps inform the user of the component’s purpose. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Layer/LayerPage.tsx b/packages/office-ui-fabric-react/src/components/Layer/LayerPage.tsx index e36eb289ae95fd..7d9ce8a6502ad9 100644 --- a/packages/office-ui-fabric-react/src/components/Layer/LayerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Layer/LayerPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { LayerBasicExample } from './examples/Layer.Basic.Example'; @@ -22,6 +23,7 @@ export class LayerPage extends React.Component { @@ -43,37 +45,22 @@ export class LayerPage extends React.Component { /> } overview={ -
-

- A Layer is a technical component that does not have specific Design guidance. -

-

- { `Layers are used to render content outside of a DOM tree, at the end of the document. This allows content to escape traditional boundaries caused by "overflow: hidden" css rules and keeps it on the top without using z-index rules. This is useful for example in ContextualMenu and Tooltip scenarios, where the content should always overlay everything else.` } -

-

{ - `There are some special considerations. Due to the nature of rendering content elsewhere asynchronously, React refs within content will not be resolvable synchronously at the time the Layer is mounted. Therefore, to use refs correctly, use functional refs ( ref={ (el) => { this._root = el; } ) rather than string refs ( ref='root' ). Additionally measuring the physical Layer element will not include any of the children, since it won't render it. Events that propgate from within the content will not go through the Layer element as well.` - }

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Layer/docs/LayerOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • { - 'Use functional refs ( ref={ (el) => { this._root = el; } ).' - } -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Layer/docs/LayerDos.md') } + } donts={ -
-
    -
  • { 'Don\'t use string refs ( ref=\'root\' ).' }
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Layer/docs/LayerDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDonts.md b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDonts.md new file mode 100644 index 00000000000000..ddf4a091d5b6d4 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDonts.md @@ -0,0 +1 @@ +- Don't use string refs `ref='root'`. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDos.md b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDos.md new file mode 100644 index 00000000000000..e0e00837259504 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerDos.md @@ -0,0 +1 @@ +- Use functional refs `ref={ (el) => { this._root = el; }`. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Layer/docs/LayerOverview.md b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerOverview.md new file mode 100644 index 00000000000000..cb8eb333474891 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Layer/docs/LayerOverview.md @@ -0,0 +1,5 @@ +A Layer is a technical component that does not have specific Design guidance. + +Layers are used to render content outside of a DOM tree, at the end of the document. This allows content to escape traditional boundaries caused by "overflow: hidden" css rules and keeps it on the top without using z-index rules. This is useful for example in ContextualMenu and Tooltip scenarios, where the content should always overlay everything else. + +There are some special considerations. Due to the nature of rendering content elsewhere asynchronously, React refs within content will not be resolvable synchronously at the time the Layer is mounted. Therefore, to use refs correctly, use functional refs `ref={ (el) => { this._root = el; }` rather than string refs `ref='root'`. Additionally measuring the physical Layer element will not include any of the children, since it won't render it. Events that propgate from within the content will not go through the Layer element as well. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Link/LinkPage.tsx b/packages/office-ui-fabric-react/src/components/Link/LinkPage.tsx index 86e45618b070be..52ddba47aae29f 100644 --- a/packages/office-ui-fabric-react/src/components/Link/LinkPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Link/LinkPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { LinkBasicExample } from './examples/Link.Basic.Example'; @@ -17,6 +18,7 @@ export class LinkPage extends React.Component { @@ -32,37 +34,22 @@ export class LinkPage extends React.Component { /> } overview={ -
-

- With a Link, users can navigate to another page, window, or Help topic; display a definition; initiate a command; or choose an option. A Link indicates that it can be clicked, typically by being displayed using the visited or unvisited link system colors. Traditionally, Links are underlined as well, but that approach is often unnecessary and falling out of favor to reduce visual clutter. -

- -

- A Link is the lightest weight clickable control, and is often used to reduce the visual complexity of a design. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Link/docs/LinkOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use to navigate to another page, window, or help topic; display a definition; initiate a command; or choose an option.
    • -
  • Make Links discoverable by visual inspection alone. Users shouldn't have to interact with your program to find links.
    • -
  • Use Links that give specific descriptive information about the result of clicking on the link, using as much text as necessary. Users should be able to accurately predict the result of a link from its link text and optional Tooltip.
    • -
  • Use text that suggests clicking, such as a command starting with an imperative verb like "Show", "Print", "Copy", or "Delete".
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Link/docs/LinkDos.md') } + } donts={ -
-
    -
  • - Use if the action is destructive or irreversible. Because users associate links with navigation (and the ability to back out), Links aren't appropriate for commands with significant consequences. -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Link/docs/LinkDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Link/docs/LinkDonts.md b/packages/office-ui-fabric-react/src/components/Link/docs/LinkDonts.md new file mode 100644 index 00000000000000..8209bbe334a41e --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Link/docs/LinkDonts.md @@ -0,0 +1 @@ +- Use if the action is destructive or irreversible. Because users associate links with navigation (and the ability to back out), Links aren't appropriate for commands with significant consequences. diff --git a/packages/office-ui-fabric-react/src/components/Link/docs/LinkDos.md b/packages/office-ui-fabric-react/src/components/Link/docs/LinkDos.md new file mode 100644 index 00000000000000..d868102317df76 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Link/docs/LinkDos.md @@ -0,0 +1,4 @@ +- Use to navigate to another page, window, or help topic; display a definition; initiate a command; or choose an option. +- Make Links discoverable by visual inspection alone. Users shouldn't have to interact with your program to find links. +- Use Links that give specific descriptive information about the result of clicking on the link, using as much text as necessary. Users should be able to accurately predict the result of a link from its link text and optional Tooltip. +- Use text that suggests clicking, such as a command starting with an imperative verb like "Show", "Print", "Copy", or "Delete". \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Link/docs/LinkOverview.md b/packages/office-ui-fabric-react/src/components/Link/docs/LinkOverview.md new file mode 100644 index 00000000000000..405f318bc8740d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Link/docs/LinkOverview.md @@ -0,0 +1,3 @@ +With a Link, users can navigate to another page, window, or Help topic; display a definition; initiate a command; or choose an option. A Link indicates that it can be clicked, typically by being displayed using the visited or unvisited link system colors. Traditionally, Links are underlined as well, but that approach is often unnecessary and falling out of favor to reduce visual clutter. + +A Link is the lightest weight clickable control, and is often used to reduce the visual complexity of a design. diff --git a/packages/office-ui-fabric-react/src/components/List/ListPage.tsx b/packages/office-ui-fabric-react/src/components/List/ListPage.tsx index 8f9ba43d51e08f..321127ea84071c 100644 --- a/packages/office-ui-fabric-react/src/components/List/ListPage.tsx +++ b/packages/office-ui-fabric-react/src/components/List/ListPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ListBasicExample } from './examples/List.Basic.Example'; @@ -32,6 +33,7 @@ export class ListPage extends React.Component { @@ -57,17 +59,9 @@ export class ListPage extends React.Component { /> } overview={ -
-

- List provides a base component for rendering large sets of items. It is agnostic of layout, the tile component used, and selection management. These concerns can be layered separately. -

-

- Performance is important, and DOM content is expensive. Therefore limit what you render. Unlike a simple for loop that renders all items in a set, a List uses ui virtualization. It only renders a subset of items, and as you scroll around, the subset of rendered content is shifted to what you're looking at. This gives a much better experience for large sets, especially when the per-item components are complex/render intensive/network intensive. -

-

- Lists break down the set of items passed in into pages. Only pages within a "materialized window" are actually rendered. As that window changes due to scroll events, pages that fall outside that window are removed, and their layout space is remembered and pushed into spacer elements. This gives the user the experience of browsing massive amounts of content but only using a small number of actual elements. This gives the browser much less layout to resolve, and gives React DOM diffing much less content to worry about. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/List/docs/ListOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/List/docs/ListOverview.md b/packages/office-ui-fabric-react/src/components/List/docs/ListOverview.md new file mode 100644 index 00000000000000..8ddcc1743928c3 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/List/docs/ListOverview.md @@ -0,0 +1,5 @@ +List provides a base component for rendering large sets of items. It is agnostic of layout, the tile component used, and selection management. These concerns can be layered separately. + +**Performance is important, and DOM content is expensive. Therefore limit what you render.** Unlike a simple for loop that renders all items in a set, a List uses ui virtualization. It only renders a subset of items, and as you scroll around, the subset of rendered content is shifted to what you're looking at. This gives a much better experience for large sets, especially when the per-item components are complex/render intensive/network intensive. + +Lists break down the set of items passed in into pages. Only pages within a "materialized window" are actually rendered. As that window changes due to scroll events, pages that fall outside that window are removed, and their layout space is remembered and pushed into spacer elements. This gives the user the experience of browsing massive amounts of content but only using a small number of actual elements. This gives the browser much less layout to resolve, and gives React DOM diffing much less content to worry about. diff --git a/packages/office-ui-fabric-react/src/components/MarqueeSelection/MarqueeSelectionPage.tsx b/packages/office-ui-fabric-react/src/components/MarqueeSelection/MarqueeSelectionPage.tsx index d1e497e7ba5cbc..69106ca199d718 100644 --- a/packages/office-ui-fabric-react/src/components/MarqueeSelection/MarqueeSelectionPage.tsx +++ b/packages/office-ui-fabric-react/src/components/MarqueeSelection/MarqueeSelectionPage.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { ExampleCard, ComponentPage, + PageMarkdown, IComponentDemoPageProps } from '@uifabric/example-app-base'; @@ -15,28 +16,16 @@ export class MarqueeSelectionPage extends React.Component } overview={ -
-

- The MarqueeSelection component provides a service which allows the user to drag a rectangle to be drawn around - items to select them. This works in conjunction with a selection object, which can be used to generically store selection state, separate from a component that consumes the state. -

-

- MarqueeSelection also works in conjunction with the AutoScroll utility to automatically scroll the container when we drag a rectangle within the vicinity of the edges. -

-

- When a selection rectangle is dragged, we look for elements with the data-selection-index attribute populated. We get these elements' boundingClientRects and compare them with the root's rect to determine selection state. We update the selection state appropriately. -

-

- In virtualization cases where items that were once selected are dematerialized, we will keep the item in its - previous state until we know definitively if it's on/off. (In other words, this works with List.) -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/MarqueeSelection/docs/MarqueeSelectionOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } /> diff --git a/packages/office-ui-fabric-react/src/components/MarqueeSelection/docs/MarqueeSelectionOverview.md b/packages/office-ui-fabric-react/src/components/MarqueeSelection/docs/MarqueeSelectionOverview.md new file mode 100644 index 00000000000000..2a3b08b9fe6199 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/MarqueeSelection/docs/MarqueeSelectionOverview.md @@ -0,0 +1,9 @@ +The MarqueeSelection component provides a service which allows the user to drag a rectangle to be drawn around +items to select them. This works in conjunction with a selection object, which can be used to generically store selection state, separate from a component that consumes the state. + +MarqueeSelection also works in conjunction with the AutoScroll utility to automatically scroll the container when we drag a rectangle within the vicinity of the edges. + +When a selection rectangle is dragged, we look for elements with the **data-selection-index** attribute populated. We get these elements' boundingClientRects and compare them with the root's rect to determine selection state. We update the selection state appropriately. + +In virtualization cases where items that were once selected are dematerialized, we will keep the item in its +previous state until we know definitively if it's on/off. (In other words, this works with List.) diff --git a/packages/office-ui-fabric-react/src/components/MessageBar/MessageBarPage.tsx b/packages/office-ui-fabric-react/src/components/MessageBar/MessageBarPage.tsx index c8ad8e9461a731..9d432d240bfbf2 100644 --- a/packages/office-ui-fabric-react/src/components/MessageBar/MessageBarPage.tsx +++ b/packages/office-ui-fabric-react/src/components/MessageBar/MessageBarPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { MessageBarBasicExample } from './examples/MessageBar.Basic.Example'; @@ -17,6 +18,7 @@ export class MessageBarPage extends React.Component /> } overview={ -
-

- A MessageBar is an area at the top of a primary view that displays relevant status information. You can use a MessageBar to tell the user about a situation that does not require their immediate attention and therefore does not need to block other activities. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/MessageBar/docs/MessageBarOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Place the message bar near the top of the relevant view, in a highly visible but unobtrusive location.
    • -
  • Keep the text very brief. Be succinct and your users are more likely to read everything you say.
    • -
  • Consider how localization may affect the message. Translation to other languages may add up to 33% more characters to the string length.
    • -
  • Use the right variant for the type and urgency of the particular message (see variants)
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDos.md') } + } donts={ -
-
    -
  • Don’t use paragraphs, long sentences, or special formatting in a MessageBar. The control tries to grow to accommodate all the text and will just result in pushing the user’s main content too low on the view.
    • -
  • Don’t use buttons when a subtler link will suffice. Reserve the usage of button for when the MessageBar has a single ”hero” action that has vital usefulness to the user at that particular moment. Using more than one button is discouraged. -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDonts.md b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDonts.md new file mode 100644 index 00000000000000..c6395569d1846e --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDonts.md @@ -0,0 +1,2 @@ +- Don’t use paragraphs, long sentences, or special formatting in a MessageBar. The control tries to grow to accommodate all the text and will just result in pushing the user’s main content too low on the view. +- Don’t use buttons when a subtler link will suffice. Reserve the usage of button for when the MessageBar has a single ”hero” action that has vital usefulness to the user at that particular moment. Using more than one button is discouraged. diff --git a/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDos.md b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDos.md new file mode 100644 index 00000000000000..e81210d598b05b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarDos.md @@ -0,0 +1,4 @@ +- Place the message bar near the top of the relevant view, in a highly visible but unobtrusive location. +- Keep the text very brief. Be succinct and your users are more likely to read everything you say. +- Consider how localization may affect the message. Translation to other languages may add up to 33% more characters to the string length. +- Use the right variant for the type and urgency of the particular message (see variants) \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarOverview.md b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarOverview.md new file mode 100644 index 00000000000000..b7ecf68c232b5c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/MessageBar/docs/MessageBarOverview.md @@ -0,0 +1 @@ +A MessageBar is an area at the top of a primary view that displays relevant status information. You can use a MessageBar to tell the user about a situation that does not require their immediate attention and therefore does not need to block other activities. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Modal/ModalPage.tsx b/packages/office-ui-fabric-react/src/components/Modal/ModalPage.tsx index 2e9c33c7742fe2..c30d1cf9098486 100644 --- a/packages/office-ui-fabric-react/src/components/Modal/ModalPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Modal/ModalPage.tsx @@ -3,6 +3,7 @@ import { ComponentPage, ExampleCard, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { Link } from 'office-ui-fabric-react/lib/Link'; @@ -18,6 +19,7 @@ export class ModalPage extends React.Component { @@ -33,37 +35,27 @@ export class ModalPage extends React.Component { /> } overview={ -
-

- Modals are temporary, modal UI overlay that generally provide contextual app information or require user confirmation/input, or can be used to advertise new app features. In some cases, Modals block interactions with the web page or application until being explicitly dismissed. They are can be used for lightweight creation or edit tasks and simple management tasks, or for hosting heavier temporary content. -

-

- For usage requiring a quick choice from the user, Dialog may be a more appropriate control. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Modal/docs/ModalOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use Modals for actionable interactions, such as needing the user to provide information or change settings.
    • -
  • When possible, try a non-blocking Modal before resorting to a blocking Modal.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Modal/docs/ModalDos.md') } + } donts={ -
-
    -
  • Don’t overuse Modals. In some cases they can be perceived as interrupting workflow, and too many can be a bad user experience.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Modal/docs/ModalDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDonts.md b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDonts.md new file mode 100644 index 00000000000000..55106e03d7405f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDonts.md @@ -0,0 +1 @@ +- Don’t overuse Modals. In some cases they can be perceived as interrupting workflow, and too many can be a bad user experience. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDos.md b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDos.md new file mode 100644 index 00000000000000..45af682a258336 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalDos.md @@ -0,0 +1,2 @@ +- Use Modals for actionable interactions, such as needing the user to provide information or change settings. +- When possible, try a non-blocking Modal before resorting to a blocking Modal. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Modal/docs/ModalOverview.md b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalOverview.md new file mode 100644 index 00000000000000..c83f71cbf1a210 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Modal/docs/ModalOverview.md @@ -0,0 +1,3 @@ +Modals are temporary, modal UI overlay that generally provide contextual app information or require user confirmation/input, or can be used to advertise new app features. In some cases, Modals block interactions with the web page or application until being explicitly dismissed. They are can be used for lightweight creation or edit tasks and simple management tasks, or for hosting heavier temporary content. + +For usage requiring a quick choice from the user, Dialog may be a more appropriate control. diff --git a/packages/office-ui-fabric-react/src/components/Nav/NavPage.tsx b/packages/office-ui-fabric-react/src/components/Nav/NavPage.tsx index 92bd70d1a9d991..a2a434497ba6d4 100644 --- a/packages/office-ui-fabric-react/src/components/Nav/NavPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Nav/NavPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { NavBasicExample } from './examples/Nav.Basic.Example'; @@ -23,6 +24,7 @@ export class NavPage extends React.Component { @@ -47,38 +49,27 @@ export class NavPage extends React.Component { /> } overview={ -
-

- Navs (also called "left nav" or "navigation pane") provide links to the main areas of an app or a site. In larger configurations, the Nav is always on-screen, usually on the left of the view. In smaller configurations, the Nav may collapse into a skinnier version or be completely hidden until the user taps an icon. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Nav/docs/NavOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use Nav for apps with many top-level navigation items that are of similar type. For example, a sports app with categories like Football, Baseball, Basketball, Soccer, and so on.
    • -
  • Keep the names of the navigation items brief and clear, rather than trying to be overly specific.
    • -
  • Use the word that feels right for the navigation. For example, some items may make better sense as nouns (e.g. “Files”), others as adjectives (“Shared”). Use what makes sense for users, and keep it short!
    • -
  • Try to keep your app’s nav in a consistent order across platforms. This sort of consistency increases predictability which drives user confidence, thus retaining and engaging them.
    • -
  • UseNav for an app with a medium to high number of top-level views or categories. If your app is very simple, you may prefer a simpler hub-and-spoke layout.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Nav/docs/NavDos.md') } + } donts={ -
-
    -
  • Overload your Nav. Too many items in the Nav is indicative of an app that is poorly organized or trying to do too much.
    • -
  • Include actions. You may reserve a space for actions, if you keep them well separated from the main Nav and their appearance makes it obvious that tapping them will execute a command instead of navigating.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Nav/docs/NavDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Nav/docs/NavDonts.md b/packages/office-ui-fabric-react/src/components/Nav/docs/NavDonts.md new file mode 100644 index 00000000000000..11c5e84cb4a8d2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Nav/docs/NavDonts.md @@ -0,0 +1,2 @@ +- Overload your Nav. Too many items in the Nav is indicative of an app that is poorly organized or trying to do too much. +- Include actions. You may reserve a space for actions, if you keep them well separated from the main Nav and their appearance makes it obvious that tapping them will execute a command instead of navigating. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Nav/docs/NavDos.md b/packages/office-ui-fabric-react/src/components/Nav/docs/NavDos.md new file mode 100644 index 00000000000000..f78fdfc189c63f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Nav/docs/NavDos.md @@ -0,0 +1,5 @@ +- Use Nav for apps with many top-level navigation items that are of similar type. For example, a sports app with categories like Football, Baseball, Basketball, Soccer, and so on. +- Keep the names of the navigation items brief and clear, rather than trying to be overly specific. +- Use the word that feels right for the navigation. For example, some items may make better sense as nouns (e.g. “Files”), others as adjectives (“Shared”). Use what makes sense for users, and keep it short! +- Try to keep your app’s nav in a consistent order across platforms. This sort of consistency increases predictability which drives user confidence, thus retaining and engaging them. +- UseNav for an app with a medium to high number of top-level views or categories. If your app is very simple, you may prefer a simpler hub-and-spoke layout. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Nav/docs/NavOverview.md b/packages/office-ui-fabric-react/src/components/Nav/docs/NavOverview.md new file mode 100644 index 00000000000000..ff696fb9a20187 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Nav/docs/NavOverview.md @@ -0,0 +1 @@ +Navs (also called "left nav" or "navigation pane") provide links to the main areas of an app or a site. In larger configurations, the Nav is always on-screen, usually on the left of the view. In smaller configurations, the Nav may collapse into a skinnier version or be completely hidden until the user taps an icon. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/OverflowSet/OverflowSetPage.tsx b/packages/office-ui-fabric-react/src/components/OverflowSet/OverflowSetPage.tsx index c003673055fb11..79bd52081d31de 100644 --- a/packages/office-ui-fabric-react/src/components/OverflowSet/OverflowSetPage.tsx +++ b/packages/office-ui-fabric-react/src/components/OverflowSet/OverflowSetPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { OverflowSetCustomExample } from './examples/OverflowSet.Custom.Example'; @@ -22,13 +23,11 @@ export class OverflowSetPage extends React.Component -

- The OverflowSet is a flexible container component that is useful for displaying a primary set of content with additional content in an overflow callout. - Note that the example below is only an example of how to render the component, not a specific use case. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/OverflowSet/docs/OverflowSetOverview.md') } + } exampleCards={ @@ -52,7 +51,7 @@ export class OverflowSetPage extends React.Component } isHeaderVisible={ this.props.isHeaderVisible } diff --git a/packages/office-ui-fabric-react/src/components/OverflowSet/docs/OverflowSetOverview.md b/packages/office-ui-fabric-react/src/components/OverflowSet/docs/OverflowSetOverview.md new file mode 100644 index 00000000000000..e1c3374a3e46b5 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/OverflowSet/docs/OverflowSetOverview.md @@ -0,0 +1 @@ +The OverflowSet is a flexible container component that is useful for displaying a primary set of content with additional content in an overflow callout. Note that the example below is only an example of how to render the component, not a specific use case. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Overlay/OverlayPage.tsx b/packages/office-ui-fabric-react/src/components/Overlay/OverlayPage.tsx index 56b3d0c1ffaf65..2b6f91ac1c1802 100644 --- a/packages/office-ui-fabric-react/src/components/Overlay/OverlayPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Overlay/OverlayPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { OverlayDarkExample } from './examples/Overlay.Dark.Example'; @@ -19,6 +20,7 @@ export class OverlayPage extends React.Component { @@ -38,29 +40,22 @@ export class OverlayPage extends React.Component { /> } overview={ -
-

- Overlays are used to render a semi-transparent layer on top of existing UI. Overlays help focus the user on the content that sits above the added layer and are often used to help designate a modal or blocking experience. Overlays can be seen used in conjunction with Panels and Dialogs. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Overlay/docs/OverlayOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a dark Overlay with a first-run experience.
    • -
  • Use a white Overlay for dialogs and panels.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Overlay/docs/OverlayDos.md') } + } donts={ -
-
    -
  • Use an Overlay when you want the user to interact with the UI that is being covered.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Overlay/docs/OverlayDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDonts.md b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDonts.md new file mode 100644 index 00000000000000..ea35603f5308a8 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDonts.md @@ -0,0 +1 @@ +- Use an Overlay when you want the user to interact with the UI that is being covered. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDos.md b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDos.md new file mode 100644 index 00000000000000..aa2ae083c7b7ec --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayDos.md @@ -0,0 +1,2 @@ +- Use a dark Overlay with a first-run experience. +- Use a white Overlay for dialogs and panels. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayOverview.md b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayOverview.md new file mode 100644 index 00000000000000..c20c1418e663a2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Overlay/docs/OverlayOverview.md @@ -0,0 +1 @@ +Overlays are used to render a semi-transparent layer on top of existing UI. Overlays help focus the user on the content that sits above the added layer and are often used to help designate a modal or blocking experience. Overlays can be seen used in conjunction with Panels and Dialogs. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Panel/PanelPage.tsx b/packages/office-ui-fabric-react/src/components/Panel/PanelPage.tsx index 11921546e8e4d8..890cab45b5ac21 100644 --- a/packages/office-ui-fabric-react/src/components/Panel/PanelPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Panel/PanelPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { PanelSmallRightExample } from './examples/Panel.SmallRight.Example'; @@ -42,6 +43,7 @@ export class PanelPage extends React.Component { @@ -93,45 +95,27 @@ export class PanelPage extends React.Component { /> } overview={ -
-

- Panels are modal UI overlays that provide contextual app information. They often request some kind of creation or management action from the user. Panels are paired with the Overlay component, also known as a Light Dismiss. The Overlay blocks interactions with the app view until dismissed either through clicking or tapping on the Overlay or by selecting a close or completion action within the Panel. -

- -

Examples of experiences that use Panels

- -
    -
  • Member or group list creation or management
    • -
  • Document list creation or management
    • -
  • Permissions creation or management
    • -
  • Settings creation or management
    • -
  • Multi-field forms
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Panel/docs/PanelOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use for self-contained experiences where the user does not need to interact with the app view to complete the task.
    • -
  • Use for complex creation, edit or management experiences.
    • -
  • Consider how the panel and its contained contents will scale across Fabric’s responsive web breakpoints.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Panel/docs/PanelDos.md') } + } donts={ -
-
    -
  • Use for experiences where the user needs to interact with the app view.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Panel/docs/PanelDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDonts.md b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDonts.md new file mode 100644 index 00000000000000..ff26f72a43a527 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDonts.md @@ -0,0 +1 @@ +- Use for experiences where the user needs to interact with the app view. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDos.md b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDos.md new file mode 100644 index 00000000000000..5772bada9a91dd --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelDos.md @@ -0,0 +1,3 @@ +- Use for self-contained experiences where the user does not need to interact with the app view to complete the task. +- Use for complex creation, edit or management experiences. +- Consider how the panel and its contained contents will scale across Fabric’s responsive web breakpoints. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Panel/docs/PanelOverview.md b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelOverview.md new file mode 100644 index 00000000000000..b658e5f59ec849 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Panel/docs/PanelOverview.md @@ -0,0 +1,9 @@ +Panels are modal UI overlays that provide contextual app information. They often request some kind of creation or management action from the user. Panels are paired with the Overlay component, also known as a Light Dismiss. The Overlay blocks interactions with the app view until dismissed either through clicking or tapping on the Overlay or by selecting a close or completion action within the Panel. + +## Examples of experiences that use Panels + +- Member or group list creation or management +- Document list creation or management +- Permissions creation or management +- Settings creation or management +- Multi-field forms \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Persona/PersonaPage.tsx b/packages/office-ui-fabric-react/src/components/Persona/PersonaPage.tsx index b318f55c8012ad..f1cabc00a92264 100644 --- a/packages/office-ui-fabric-react/src/components/Persona/PersonaPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Persona/PersonaPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { PersonaInitialsExample } from './examples/Persona.Initials.Example'; @@ -25,6 +26,7 @@ export class PersonaPage extends React.Component { @@ -53,31 +55,22 @@ export class PersonaPage extends React.Component { /> } overview={ -
-

- Personas are used for rendering an individual's avatar and presence. They are used within the PeoplePicker components. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Persona/docs/PersonaOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use Size 24 Persona in text fields in read mode or in experiences such as multi-column list view which need compact Persona representations.
    • -
  • Use Size 32 Persona in text fields in edit mode.
    • -
  • Use Size 32, Size 40, and Size 48 Personas in menus and list views.
    • -
  • Use Size 72 and Size 100 Personas in profile cards and views.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Persona/docs/PersonaDos.md') } + } donts={ -
-
    -
  • Change the values of the color swatches in high contrast mode.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Persona/docs/PersonaDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDonts.md b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDonts.md new file mode 100644 index 00000000000000..ca3763b7b1e261 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDonts.md @@ -0,0 +1 @@ +- Change the values of the color swatches in high contrast mode. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDos.md b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDos.md new file mode 100644 index 00000000000000..d062adb79ed5f2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaDos.md @@ -0,0 +1,4 @@ +- Use Size 24 Persona in text fields in read mode or in experiences such as multi-column list view which need compact Persona representations. +- Use Size 32 Persona in text fields in edit mode. +- Use Size 32, Size 40, and Size 48 Personas in menus and list views. +- Use Size 72 and Size 100 Personas in profile cards and views. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaOverview.md b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaOverview.md new file mode 100644 index 00000000000000..10ba58c6958d54 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Persona/docs/PersonaOverview.md @@ -0,0 +1 @@ +Personas are used for rendering an individual's avatar and presence. They are used within the PeoplePicker components. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Pivot/PivotPage.tsx b/packages/office-ui-fabric-react/src/components/Pivot/PivotPage.tsx index 37c8c6a06ad37b..f19ad9ce968951 100644 --- a/packages/office-ui-fabric-react/src/components/Pivot/PivotPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Pivot/PivotPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { PivotBasicExample } from './examples/Pivot.Basic.Example'; @@ -35,6 +36,7 @@ export class PivotPage extends React.Component { @@ -79,43 +81,22 @@ export class PivotPage extends React.Component { /> } overview={ -
-

- The Pivot control and related tabs pattern are used for navigating frequently accessed, distinct content categories. Pivots allow for navigation between two or more content views and relies on text headers to articulate the different sections of content. -

- -
    -
  • Tapping on a pivot item header navigates to that header's section content.
    • -
  • Swiping left or right on a pivot item header navigates to the adjacent section.
    • -
  • Swiping left or right on section content navigates to the adjacent section.
    • -
  • Pivots are stationary when all pivot headers fit within the allowed space.
    • -
  • Pivots carousel when all pivot headers don't fit within the allowed space.
    • -
- -

- Tabs are a visual variant of Pivot that use a combination of icons and text or just icons to articulate section content. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Pivot/docs/PivotOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use on content-heavy pages that require a significant amount of scrolling to access the various sections.
    • -
  • Be concise on the navigation labels, ideally one or two words rather than a phrase.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Pivot/docs/PivotDos.md') } + } donts={ -
-
    -
  • Don’t use on pages which doesn’t scroll.
    • -
  • Don’t use the Pivot to link to a new page.
    • -
  • Don’t use the Pivot to link to hidden content.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Pivot/docs/PivotDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDonts.md b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDonts.md new file mode 100644 index 00000000000000..6915a809d8159c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDonts.md @@ -0,0 +1,3 @@ +- Don’t use on pages which doesn’t scroll. +- Don’t use the Pivot to link to a new page. +- Don’t use the Pivot to link to hidden content. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDos.md b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDos.md new file mode 100644 index 00000000000000..759f4498948c6c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotDos.md @@ -0,0 +1,2 @@ +- Use on content-heavy pages that require a significant amount of scrolling to access the various sections. +- Be concise on the navigation labels, ideally one or two words rather than a phrase. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotOverview.md b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotOverview.md new file mode 100644 index 00000000000000..71d82f61121f20 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Pivot/docs/PivotOverview.md @@ -0,0 +1,9 @@ +The Pivot control and related tabs pattern are used for navigating frequently accessed, distinct content categories. Pivots allow for navigation between two or more content views and relies on text headers to articulate the different sections of content. + +- Tapping on a pivot item header navigates to that header's section content. +- Swiping left or right on a pivot item header navigates to the adjacent section. +- Swiping left or right on section content navigates to the adjacent section. +- Pivots are stationary when all pivot headers fit within the allowed space. +- Pivots carousel when all pivot headers don't fit within the allowed space. + +Tabs are a visual variant of Pivot that use a combination of icons and text or just icons to articulate section content. diff --git a/packages/office-ui-fabric-react/src/components/ProgressIndicator/ProgressIndicatorPage.tsx b/packages/office-ui-fabric-react/src/components/ProgressIndicator/ProgressIndicatorPage.tsx index 85746ac5d3bd42..7cdce5709ba9bc 100644 --- a/packages/office-ui-fabric-react/src/components/ProgressIndicator/ProgressIndicatorPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ProgressIndicator/ProgressIndicatorPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ProgressIndicatorBasicExample } from './examples/ProgressIndicator.Basic.Example'; @@ -19,6 +20,7 @@ export class ProgressIndicatorPage extends React.Component @@ -37,60 +39,27 @@ export class ProgressIndicatorPage extends React.Component } overview={ -
-

- ProgressIndicators are used to show the completion status of an operation lasting more than 2 seconds. If the state of progress cannot be determined, use a Spinner instead. ProgressIndicators can appear in a new panel, a flyout, under the UI initiating the operation, or even replacing the initiating UI, as long as the UI can return if the operation is canceled or is stopped. -

-

- ProgressIndicators feature a bar showing total units to completion, and total units finished. The description of the operation appears above the bar, and the status in text appears below. The description should tell someone exactly what the operation is doing. Examples of formatting include: -

-
    -
  • - [Object] is being [operation name], or -
    • -
  • - [Object] is being [operation name] to [destination name] or -
    • -
  • - [Object] is being [operation name] from [source name] to [destination name] -
    • -
-

- Status text is generally in units elapsed and total units. If the operation can be canceled, an “X” icon is used and should be placed in the upper right, aligned with the baseline of the operation name. When an error occurs, replace the status text with the error description using ms-fontColor-redDark. -

-

- Real-world examples include copying files to a storage location, saving edits to a file, and more. Use units that are informative and relevant to give the best idea to users of how long the operation will take to complete. Avoid time units as they are rarely accurate enough to be trustworthy. Also, combine steps of a complex operation into one total bar to avoid “rewinding” the bar. Instead change the operation description to reflect the change if necessary. Bars moving backwards reduce confidence in the service. -

- -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a ProgressIndicator when the total units to completion is known
    • -
  • Display operation description
    • -
  • Show text above and/or below the bar
    • -
  • Combine steps of a single operation into one bar
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDos.md') } + } donts={ -
-
    -
  • Use a ProgressIndicator when the total units to completion is indeterminate
    • -
  • Use only a single word description
    • -
  • Show text to the right or left of the bar
    • -
  • Cause progress to “rewind” to show new steps
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDonts.md b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDonts.md new file mode 100644 index 00000000000000..5138b92a4f299d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDonts.md @@ -0,0 +1,4 @@ +- Use a ProgressIndicator when the total units to completion is indeterminate +- Use only a single word description +- Show text to the right or left of the bar +- Cause progress to “rewind” to show new steps \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDos.md b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDos.md new file mode 100644 index 00000000000000..4c12cb8ba1d0d6 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorDos.md @@ -0,0 +1,4 @@ +- Use a ProgressIndicator when the total units to completion is known +- Display operation description +- Show text above and/or below the bar +- Combine steps of a single operation into one bar \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorOverview.md b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorOverview.md new file mode 100644 index 00000000000000..6a7148ba3d5b3a --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ProgressIndicator/docs/ProgressIndicatorOverview.md @@ -0,0 +1,11 @@ +ProgressIndicators are used to show the completion status of an operation lasting more than 2 seconds. If the state of progress cannot be determined, use a Spinner instead. ProgressIndicators can appear in a new panel, a flyout, under the UI initiating the operation, or even replacing the initiating UI, as long as the UI can return if the operation is canceled or is stopped. + +ProgressIndicators feature a bar showing total units to completion, and total units finished. The description of the operation appears above the bar, and the status in text appears below. The description should tell someone exactly what the operation is doing. Examples of formatting include: + +- **[Object]** is being **[operation name]**, or +- **[Object]** is being **[operation name]** to **[destination name]** or +- **[Object]** is being **[operation name]** from **[source name]** to **[destination name]** + +Status text is generally in units elapsed and total units. If the operation can be canceled, an “X” icon is used and should be placed in the upper right, aligned with the baseline of the operation name. When an error occurs, replace the status text with the error description using ms-fontColor-redDark. + +Real-world examples include copying files to a storage location, saving edits to a file, and more. Use units that are informative and relevant to give the best idea to users of how long the operation will take to complete. Avoid time units as they are rarely accurate enough to be trustworthy. Also, combine steps of a complex operation into one total bar to avoid “rewinding” the bar. Instead change the operation description to reflect the change if necessary. Bars moving backwards reduce confidence in the service. diff --git a/packages/office-ui-fabric-react/src/components/Rating/RatingPage.tsx b/packages/office-ui-fabric-react/src/components/Rating/RatingPage.tsx index 476537b62615c5..3f31c3ad22baf5 100644 --- a/packages/office-ui-fabric-react/src/components/Rating/RatingPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Rating/RatingPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { RatingBasicExample } from './examples/Rating.Basic.Example'; @@ -17,6 +18,7 @@ export class RatingPage extends React.Component { @@ -30,33 +32,27 @@ export class RatingPage extends React.Component { /> } overview={ -
-

- Ratings provide insight regarding others’ opinions and experiences with a product, helping users make more-informed purchasing decisions. Users can also rate products they’ve purchased. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Rating/docs/RatingOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Make it clear which product the rating pertains to by making sure the layout and grouping are clear when several products are on the page.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Rating/docs/RatingDos.md') } + } donts={ -
-
    -
  • Don’t use the rating component for data that has a continuous range, such as the brightness of a photo. Instead, use a slider.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Rating/docs/RatingDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDonts.md b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDonts.md new file mode 100644 index 00000000000000..1e7800f804a206 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDonts.md @@ -0,0 +1 @@ +- Don’t use the rating component for data that has a continuous range, such as the brightness of a photo. Instead, use a slider. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDos.md b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDos.md new file mode 100644 index 00000000000000..a56a299d1738cc --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingDos.md @@ -0,0 +1 @@ +- Make it clear which product the rating pertains to by making sure the layout and grouping are clear when several products are on the page. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Rating/docs/RatingOverview.md b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingOverview.md new file mode 100644 index 00000000000000..89e7faca684f19 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Rating/docs/RatingOverview.md @@ -0,0 +1 @@ +Ratings provide insight regarding others’ opinions and experiences with a product, helping users make more-informed purchasing decisions. Users can also rate products they’ve purchased. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ResizeGroup/ResizeGroupPage.tsx b/packages/office-ui-fabric-react/src/components/ResizeGroup/ResizeGroupPage.tsx index b7fa1d5d97d6d3..66fbb7b927d0e5 100644 --- a/packages/office-ui-fabric-react/src/components/ResizeGroup/ResizeGroupPage.tsx +++ b/packages/office-ui-fabric-react/src/components/ResizeGroup/ResizeGroupPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ResizeGroupOverflowSetExample } from './examples/ResizeGroup.OverflowSet.Example'; @@ -21,6 +22,7 @@ export class ResizeGroupPage extends React.Component @@ -40,66 +42,22 @@ export class ResizeGroupPage extends React.Component } overview={ -
- -

- ResizeGroup is a React component that can be used to help fit the right amount of content within a container. The consumer - of the ResizeGroup provides some initial data, a reduce function, and a render function. The render function is responsible - for populating the contents of a the container when given some data. The initial data should represent the data that should - be rendered when the ResizeGroup has infinite width. If the contents returned by the render function do not fit within the - ResizeGroup, the reduce function is called to get a version of the data whose rendered width should be smaller than the data - that was just rendered. -

-

- An example scenario is shown below, where controls that do not fit on screen are rendered in an overflow menu. The data in - this situation is a list of 'primary' controls that are rendered on the top level and a set of overflow controls rendered in - the overflow menu. The initial data in this case has all the controls in the primary set. The implementation of onReduceData - moves a control from the overflow well into the primary control set. -

-

- This component queries the DOM for the dimensions of elements. Too many of these dimension queries will negatively affect - the performance of the component and could cause poor interactive performance on websites. One way to reduce the number of - measurements performed by the component is to provide a cacheKey in the initial data and in the return value of - onReduceData. Two data objects with the same cacheKey are assumed to have the same width, resulting in measurements being - skipped for that data object. In the controls with an overflow example, the cacheKey is simply the concatenation of the - keys of the controls that appear in the top level. -

-

- There is a boolean context property (isMeasured) added to let child components know if they are only being used for measurement purposes. When isMeasured is true, it will signify that the component is not the instance visible to the user. This will not be needed for most scenarios. It is intended to be used to to skip unwanted side effects of mounting a child component more than once. This includes cases where the the component makes API requests, requests focus to one of its elements, expensive computations, and/or renders markup unrelated to its size. Be careful not to use this property to change the components rendered output in a way that effects it size in any way. -

- -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • - Ensure the width of the parent of this component has a fixed width that does not depend on the dimensions of it's children. - Failure to do so may result in ResizeGroup attempting to fill a width of 0px. -
    • -
  • - Ensure that result of rendering the data returned by onReduceData is actually smaller than the previous data. -
    • -
  • - Include a cacheKey in your data to improve performance. Two objects with the same cacheKey are assumed to have the same - width, so the ResizeGroup will only store one measurement per resize group. -
    • -
  • - Implement onGrowData for improved performance when the container for the resize group increases in size. -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDos.md') } + } donts={ -
-
    -
  • Do any DOM measurements inside your onReduce function as this will degrade performance
    • -
  • Provide too many different return values for onReduce, it will degrade performance
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDonts.md b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDonts.md new file mode 100644 index 00000000000000..4e5e957772a25f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDonts.md @@ -0,0 +1,2 @@ +- Do any DOM measurements inside your onReduce function as this will degrade performance +- Provide too many different return values for onReduce, it will degrade performance \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDos.md b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDos.md new file mode 100644 index 00000000000000..12de3cc5919f1c --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupDos.md @@ -0,0 +1,4 @@ +- Ensure the width of the parent of this component has a fixed width that does not depend on the dimensions of it's children. Failure to do so may result in ResizeGroup attempting to fill a width of 0px. +- Ensure that result of rendering the data returned by onReduceData is actually smaller than the previous data. +- Include a cacheKey in your data to improve performance. Two objects with the same cacheKey are assumed to have the same width, so the ResizeGroup will only store one measurement per resize group. +- Implement onGrowData for improved performance when the container for the resize group increases in size. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupOverview.md b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupOverview.md new file mode 100644 index 00000000000000..d2295068c8ae40 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ResizeGroup/docs/ResizeGroupOverview.md @@ -0,0 +1,7 @@ +ResizeGroup is a React component that can be used to help fit the right amount of content within a container. The consumer of the ResizeGroup provides some initial data, a reduce function, and a render function. The render function is responsible for populating the contents of a the container when given some data. The initial data should represent the data that should be rendered when the ResizeGroup has infinite width. If the contents returned by the render function do not fit within the ResizeGroup, the reduce function is called to get a version of the data whose rendered width should be smaller than the data that was just rendered. + +An example scenario is shown below, where controls that do not fit on screen are rendered in an overflow menu. The data in this situation is a list of 'primary' controls that are rendered on the top level and a set of overflow controls rendered in the overflow menu. The initial data in this case has all the controls in the primary set. The implementation of onReduceData moves a control from the overflow well into the primary control set. + +This component queries the DOM for the dimensions of elements. Too many of these dimension queries will negatively affect the performance of the component and could cause poor interactive performance on websites. One way to reduce the number of measurements performed by the component is to provide a cacheKey in the initial data and in the return value of onReduceData. Two data objects with the same cacheKey are assumed to have the same width, resulting in measurements being skipped for that data object. In the controls with an overflow example, the cacheKey is simply the concatenation of the keys of the controls that appear in the top level. + +There is a boolean context property (isMeasured) added to let child components know if they are only being used for measurement purposes. When isMeasured is true, it will signify that the component is not the instance visible to the user. This will not be needed for most scenarios. It is intended to be used to to skip unwanted side effects of mounting a child component more than once. This includes cases where the the component makes API requests, requests focus to one of its elements, expensive computations, and/or renders markup unrelated to its size. Be careful not to use this property to change the components rendered output in a way that effects it size in any way. diff --git a/packages/office-ui-fabric-react/src/components/ScrollablePane/ScrollablePanePage.tsx b/packages/office-ui-fabric-react/src/components/ScrollablePane/ScrollablePanePage.tsx index 86abb63498a324..170577ea911936 100644 --- a/packages/office-ui-fabric-react/src/components/ScrollablePane/ScrollablePanePage.tsx +++ b/packages/office-ui-fabric-react/src/components/ScrollablePane/ScrollablePanePage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ScrollablePaneDefaultExample } from './examples/ScrollablePane.Default.Example'; @@ -20,6 +21,7 @@ export class ScrollablePanePage extends React.Component @@ -43,30 +45,22 @@ export class ScrollablePanePage extends React.Component } overview={ -
-

- ScrollablePane is a helper component designed to use in conjunction with a Sticky component. Sticky components will "stick" to the top or bottom of a ScrollablePane's scrollable region and remain visible. ScrollablePane requires a height or max-height set either on the component itself, or on the immediate parent element. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Ensure that a parent component has a CSS height, or max-height attribute set (and any intermediary containers have an inherit, or explicit height/max-height set).
    • -
  • Use Sticky component on block level elements
    • -
  • Sticky component are ideally section headers and/or footers
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDos.md') } + } donts={ -
-
    -
  • Don't use Sticky on elements with margin top or bottom
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDonts.md b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDonts.md new file mode 100644 index 00000000000000..84f8a79e0cc17a --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDonts.md @@ -0,0 +1 @@ +- Don't use Sticky on elements with margin top or bottom \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDos.md b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDos.md new file mode 100644 index 00000000000000..4c729aeea7ccad --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneDos.md @@ -0,0 +1,3 @@ +- Ensure that a parent component has a CSS height, or max-height attribute set (and any intermediary containers have an inherit, or explicit height/max-height set). +- Use Sticky component on block level elements +- Sticky component are ideally section headers and/or footers \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneOverview.md b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneOverview.md new file mode 100644 index 00000000000000..0bcd8f171c5bbf --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/ScrollablePane/docs/ScrollablePaneOverview.md @@ -0,0 +1 @@ +ScrollablePane is a helper component designed to use in conjunction with a Sticky component. Sticky components will "stick" to the top or bottom of a ScrollablePane's scrollable region and remain visible. ScrollablePane requires a height or max-height set either on the component itself, or on the immediate parent element. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SearchBox/SearchBoxPage.tsx b/packages/office-ui-fabric-react/src/components/SearchBox/SearchBoxPage.tsx index d8e4ff0d94ddce..1003d0eaaead2d 100644 --- a/packages/office-ui-fabric-react/src/components/SearchBox/SearchBoxPage.tsx +++ b/packages/office-ui-fabric-react/src/components/SearchBox/SearchBoxPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { SearchBoxFullSizeExample } from './examples/SearchBox.FullSize.Example'; @@ -24,6 +25,7 @@ export class SearchBoxPage extends React.Component /> } overview={ -
-

- SearchBoxes provide an input field for searching through content, allowing users to locate specific items within the website or app. -

- -

Zero input state

- -

- When the user has clicked into the SearchBox, but has not entered any text, there is an opportunity to display "hint text" within the input field, explaining what a user can do next. This could prompt a user to search for specific type content, or explain the scope of the search. Examples include "type to search", "try searching for <x>", "search for a place" or "type to search in <x location>". -

- -

Autocomplete suggestions

- -

- As the user enters a query string, they are provided with a dropdown of autocomplete suggestions or disambiguation options. This will help them expedite the input process and formulate an effective query. Recent search history, trending searches, contextual search suggestions, hints and tips are all good candidates for autocomplete content. In general, autocomplete suggestions have the user's input highlighted in some way (generally bolded) to indicate why it's being displayed. As the user enters more keystrokes, the suggestions update continuously/in real time. To see autocomplete suggestions, the user does not need to hit enter (execute a full search), as it is a lightweight way to get quick suggestions or results. If there are mixed result types within the autocomplete suggestions, provide visual indicators or grouping to help organize the information, making it easier to parse. -

- -

Full search

- -

- If a user hits "enter" after entering input, a full search is executed. Full searches often go to another "results" page, or change/filter the content of the current page to show only applicable content. The results can appear in any form that best communicates the content. -

- -

- As a general guideline, results should be displayed in context with the query that was typed, with immediate access to edit the query or enter a new one. One method to enable efficient access to both edit the previous query and enter a new query is to highlight the previous query when the field is reactivated. This way, any keystroke will replace the previous string, but the string is maintained so that the user can position a cursor to edit or append the previous string. -

- -

Search scopes

- -

- Although search entry points tend to be similarly visualized, they can provide access to results that range from broad to narrow. By effectively communicating the scope of a search, you can help to ensure that the user expectation will be met by the capabilities of the search you are performing, which will reduce the possibility of frustration. The search entry point should be juxtaposed with the content being searched. -

- -

- Some common search scopes include: -

- -
    -
  • Global: Search across multiple sources of cloud and local content. Varied results include URLs, documents, media, actions, apps, and more.
    • -
  • Web: Search a web index. Results include pages, entities, and answers.
    • -
  • My stuff: Search across device(s), cloud, social graphs, and more. Results are varied, but are constrained by the connection to user account(s).
    • -
- -

SearchBox with no parent container

- -

- Use a SearchBox without a parent container when it is not restricted to a certain width to accommodate other content. This search box will span the entire width of the space it's in. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use placeholder text in the SearchBox to describe what users can search for.
    • -
  • Example: "Search"; "Search files"; "Search site"
    • -
  • Once the user has clicked into the SearchBox but hasn’t entered input yet, use "hint text" to communicate search scope.
    • -
  • Examples: "Try searching for a PDFs"; "Search contacts list"; "Type to find <content type>"
    • -
  • Provide autocomplete suggestions to help the user search quickly. These suggestions can be from past searches or auto-completions of the user's query text.
    • -
  • Provide autocomplete suggestions where there are strong matches to the user's query that the user may want to view immediately.
    • -
  • Use a visual separator to define a group of a similar or conceptually aligned autocomplete suggestions.
    • -
  • If possible, provide a preview (e.g. image, title, etc.) for autocomplete suggestions to help the user quickly determine if the suggested result is what they were searching for.
    • -
  • Use the Underlined SearchBox for CommandBars.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDos.md') } + } donts={ -
-
    -
  • Don't leave the SearchBox blank because it's too ambiguous.
    • -
  • Don't have lengthy and unclear hint text. It should be used to clarify and set expectations.
    • -
  • Don't provide too many autocomplete suggestions, as that will overwhelm the user.
    • -
  • Don't provide inaccurate matches or bad predictions, as it will make search seem unreliable and will result in user frustration.
    • -
  • Don’t provide too much information or metadata in the suggestions list; it’s intended to be lightweight.
    • -
  • Don’t use an autocomplete dropdown for something that has one choice; there must be more than one item.
    • -
  • Don't build a custom search control based on the default text box or any other control.
    • -
  • Don't use SearchBox if you cannot reliably provide accurate results.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDonts.md b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDonts.md new file mode 100644 index 00000000000000..bb977a155edf5e --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDonts.md @@ -0,0 +1,8 @@ +- Don't leave the SearchBox blank because it's too ambiguous. +- Don't have lengthy and unclear hint text. It should be used to clarify and set expectations. +- Don't provide too many autocomplete suggestions, as that will overwhelm the user. +- Don't provide inaccurate matches or bad predictions, as it will make search seem unreliable and will result in user frustration. +- Don’t provide too much information or metadata in the suggestions list; it’s intended to be lightweight. +- Don’t use an autocomplete dropdown for something that has one choice; there must be more than one item. +- Don't build a custom search control based on the default text box or any other control. +- Don't use SearchBox if you cannot reliably provide accurate results. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDos.md b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDos.md new file mode 100644 index 00000000000000..9de49cc7727a29 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxDos.md @@ -0,0 +1,9 @@ +- Use placeholder text in the SearchBox to describe what users can search for. +- Example: "Search"; "Search files"; "Search site" +- Once the user has clicked into the SearchBox but hasn’t entered input yet, use "hint text" to communicate search scope. +- Examples: "Try searching for a PDFs"; "Search contacts list"; "Type to find \" +- Provide autocomplete suggestions to help the user search quickly. These suggestions can be from past searches or auto-completions of the user's query text. +- Provide autocomplete suggestions where there are strong matches to the user's query that the user may want to view immediately. +- Use a visual separator to define a group of a similar or conceptually aligned autocomplete suggestions. +- If possible, provide a preview (e.g. image, title, etc.) for autocomplete suggestions to help the user quickly determine if the suggested result is what they were searching for. +- Use the Underlined SearchBox for CommandBars. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxOverview.md b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxOverview.md new file mode 100644 index 00000000000000..a0b55e39b7aa93 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SearchBox/docs/SearchBoxOverview.md @@ -0,0 +1,29 @@ +SearchBoxes provide an input field for searching through content, allowing users to locate specific items within the website or app. + +## Zero input state + +When the user has clicked into the SearchBox, but has not entered any text, there is an opportunity to display "hint text" within the input field, explaining what a user can do next. This could prompt a user to search for specific type content, or explain the scope of the search. Examples include "type to search", "try searching for \", "search for a place" or "type to search in \". + +## Autocomplete suggestions + +As the user enters a query string, they are provided with a dropdown of autocomplete suggestions or disambiguation options. This will help them expedite the input process and formulate an effective query. Recent search history, trending searches, contextual search suggestions, hints and tips are all good candidates for autocomplete content. In general, autocomplete suggestions have the user's input highlighted in some way (generally bolded) to indicate why it's being displayed. As the user enters more keystrokes, the suggestions update continuously/in real time. To see autocomplete suggestions, the user does not need to hit enter (execute a full search), as it is a lightweight way to get quick suggestions or results. If there are mixed result types within the autocomplete suggestions, provide visual indicators or grouping to help organize the information, making it easier to parse. + +## Full search + +If a user hits "enter" after entering input, a full search is executed. Full searches often go to another "results" page, or change/filter the content of the current page to show only applicable content. The results can appear in any form that best communicates the content. + +As a general guideline, results should be displayed in context with the query that was typed, with immediate access to edit the query or enter a new one. One method to enable efficient access to both edit the previous query and enter a new query is to highlight the previous query when the field is reactivated. This way, any keystroke will replace the previous string, but the string is maintained so that the user can position a cursor to edit or append the previous string. + +## Search scopes + +Although search entry points tend to be similarly visualized, they can provide access to results that range from broad to narrow. By effectively communicating the scope of a search, you can help to ensure that the user expectation will be met by the capabilities of the search you are performing, which will reduce the possibility of frustration. The search entry point should be juxtaposed with the content being searched. + +Some common search scopes include: + +- **Global:** Search across multiple sources of cloud and local content. Varied results include URLs, documents, media, actions, apps, and more. +- **Web:** Search a web index. Results include pages, entities, and answers. +- **My stuff:** Search across device(s), cloud, social graphs, and more. Results are varied, but are constrained by the connection to user account(s). + +## SearchBox with no parent container + +Use a SearchBox without a parent container when it is not restricted to a certain width to accommodate other content. This search box will span the entire width of the space it's in. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Slider/SliderPage.tsx b/packages/office-ui-fabric-react/src/components/Slider/SliderPage.tsx index b14469fdf530ff..20f451739208af 100644 --- a/packages/office-ui-fabric-react/src/components/Slider/SliderPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Slider/SliderPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { SliderBasicExample } from './examples/Slider.Basic.Example'; @@ -17,6 +18,7 @@ export class SliderPage extends React.Component { @@ -30,43 +32,27 @@ export class SliderPage extends React.Component { /> } overview={ -
-

- A Slider is an element used to set a value. It provides a visual indication of adjustable content, as well as the current setting in the total range of content. It is displayed as a horizontal track with options on either side. A knob or lever is dragged to one end or the other to make the choice, indicating the current value. Marks on the Slider bar can show values and users can choose where they want to drag the knob or lever to set the value. -

-

- A Slider is a good choice when you know that users think of the value as a relative quantity, not a numeric value. For example, users think about setting their audio volume to low or medium—not about setting the value to two or five. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Slider/docs/SliderOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Consider a Slider when changing a value.
    • -
  • Use a slider when you want your users to be able to set defined values (such as volume or brightness).
    • -
  • Include a label indicating what value the Slider changes.
    • -
  • Use step points (or tick marks) if you don’t want the Slider to allow arbitrary values between min and max.
    • -
  • Use a Slider when the user would benefit from instant feedback on the effect of setting changes.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Slider/docs/SliderDos.md') } + } donts={ -
-
    -
  • Don't use a Slider when the options are not values.
    • -
  • Don’t use a Slider for binary settings.
    • -
  • Don’t create a continuous Slider if the range of values is large.
    • -
  • Don’t use for a range of three values or less.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Slider/docs/SliderDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDonts.md b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDonts.md new file mode 100644 index 00000000000000..3d5cbad81fc63d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDonts.md @@ -0,0 +1,4 @@ +- Don't use a Slider when the options are not values. +- Don’t use a Slider for binary settings. +- Don’t create a continuous Slider if the range of values is large. +- Don’t use for a range of three values or less. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDos.md b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDos.md new file mode 100644 index 00000000000000..336a1ec3087a06 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderDos.md @@ -0,0 +1,5 @@ +- Consider a Slider when changing a value. +- Use a slider when you want your users to be able to set defined values (such as volume or brightness). +- Include a label indicating what value the Slider changes. +- Use step points (or tick marks) if you don’t want the Slider to allow arbitrary values between min and max. +- Use a Slider when the user would benefit from instant feedback on the effect of setting changes. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Slider/docs/SliderOverview.md b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderOverview.md new file mode 100644 index 00000000000000..0b7c0e00e7c2e1 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Slider/docs/SliderOverview.md @@ -0,0 +1,3 @@ +A Slider is an element used to set a value. It provides a visual indication of adjustable content, as well as the current setting in the total range of content. It is displayed as a horizontal track with options on either side. A knob or lever is dragged to one end or the other to make the choice, indicating the current value. Marks on the Slider bar can show values and users can choose where they want to drag the knob or lever to set the value. + +A Slider is a good choice when you know that users think of the value as a relative quantity, not a numeric value. For example, users think about setting their audio volume to low or medium—not about setting the value to two or five. diff --git a/packages/office-ui-fabric-react/src/components/SpinButton/SpinButtonPage.tsx b/packages/office-ui-fabric-react/src/components/SpinButton/SpinButtonPage.tsx index faa27929fd1e64..5f95b7b953c06e 100644 --- a/packages/office-ui-fabric-react/src/components/SpinButton/SpinButtonPage.tsx +++ b/packages/office-ui-fabric-react/src/components/SpinButton/SpinButtonPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { SpinButtonBasicExample } from './examples/SpinButton.Basic.Example'; @@ -30,6 +31,7 @@ export class SpinButtonPage extends React.Component /> } overview={ -
-

- A SpinButton allows the user to incrementaly adjust a value in small steps. It is mainly used for numeric values, but other values are supported too. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a SpinButton when changing a value with precise control.
    • -
  • Use a SpinButton when values are tied to a unit.
    • -
  • Include a label indicating what value the SpinButton changes.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDos.md') } + } donts={ -
-
    -
  • Don’t use a SpinButton if the range of values is large.
    • -
  • Don’t use a SpinButton for binary settings.
    • -
  • Don't use a SpinButton for a range of three values or less.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDonts.md b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDonts.md new file mode 100644 index 00000000000000..6c04426cee37ad --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDonts.md @@ -0,0 +1,3 @@ +- Don’t use a SpinButton if the range of values is large. +- Don’t use a SpinButton for binary settings. +- Don't use a SpinButton for a range of three values or less. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDos.md b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDos.md new file mode 100644 index 00000000000000..9b76bf0893ed0a --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonDos.md @@ -0,0 +1,3 @@ +- Use a SpinButton when changing a value with precise control. +- Use a SpinButton when values are tied to a unit. +- Include a label indicating what value the SpinButton changes. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonOverview.md b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonOverview.md new file mode 100644 index 00000000000000..8c27fca6c4652d --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SpinButton/docs/SpinButtonOverview.md @@ -0,0 +1 @@ +A SpinButton allows the user to incrementaly adjust a value in small steps. It is mainly used for numeric values, but other values are supported too. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Spinner/SpinnerPage.tsx b/packages/office-ui-fabric-react/src/components/Spinner/SpinnerPage.tsx index 4f5a537acafa7f..b7d0a5e63fd958 100644 --- a/packages/office-ui-fabric-react/src/components/Spinner/SpinnerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Spinner/SpinnerPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { SpinnerBasicExample } from './examples/Spinner.Basic.Example'; @@ -17,6 +18,7 @@ export class SpinnerPage extends React.Component { { /> } overview={ -
-

- A Spinner is an outline of a circle which animates around itself indicating to the user that things are processing. A Spinner is shown when it's unsure how long a task will take making it the indeterminate version of a ProgressIndicator. They can be various sizes, located inline with content or centered. They generally appear after an action is being processed or committed. They are subtle and generally do not take up much space, but are transitions from the completed task. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use a Spinner when a task is not immediate.
    • -
  • Use one Spinner at a time.
    • -
  • Descriptive verbs are appropriate under a Spinner to help the user understand what's happening. Ie: Saving, processing, updating.
    • -
  • Use a Spinner when confirming a change has been made or a task is being processed.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerDos.md') } + } donts={ -
-
    -
  • Don’t use a Spinner when performing immediate tasks.
    • -
  • Don't show multiple Spinners at the same time.
    • -
  • Don't include more than a few words when paired with a Spinner.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDonts.md b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDonts.md new file mode 100644 index 00000000000000..d265a7d6eb922f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDonts.md @@ -0,0 +1,3 @@ +- Don’t use a Spinner when performing immediate tasks. +- Don't show multiple Spinners at the same time. +- Don't include more than a few words when paired with a Spinner. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDos.md b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDos.md new file mode 100644 index 00000000000000..39e616d86e2443 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerDos.md @@ -0,0 +1,4 @@ +- Use a Spinner when a task is not immediate. +- Use one Spinner at a time. +- Descriptive verbs are appropriate under a Spinner to help the user understand what's happening. Ie: Saving, processing, updating. +- Use a Spinner when confirming a change has been made or a task is being processed. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerOverview.md b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerOverview.md new file mode 100644 index 00000000000000..5e7970a9b658ea --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Spinner/docs/SpinnerOverview.md @@ -0,0 +1 @@ +A Spinner is an outline of a circle which animates around itself indicating to the user that things are processing. A Spinner is shown when it's unsure how long a task will take making it the indeterminate version of a ProgressIndicator. They can be various sizes, located inline with content or centered. They generally appear after an action is being processed or committed. They are subtle and generally do not take up much space, but are transitions from the completed task. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SwatchColorPicker/SwatchColorPickerPage.tsx b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/SwatchColorPickerPage.tsx index 0fae1ac85b1c29..f349be46b95e66 100644 --- a/packages/office-ui-fabric-react/src/components/SwatchColorPicker/SwatchColorPickerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/SwatchColorPickerPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, IComponentDemoPageProps, ComponentPage, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { SwatchColorPickerBasicExample } from './examples/SwatchColorPicker.Basic.Example'; @@ -17,6 +18,7 @@ export class SwatchColorPickerPage extends React.Component @@ -30,31 +32,27 @@ export class SwatchColorPickerPage extends React.Component } overview={ -
-

- A SwatchColorPicker is a list of colors displayed as a grid as options for the user. It can be displayed by itself, with header and/or dividers, or as a button which expands to show the swatch color picker -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerOverview.md') } + + } + bestPractices={ +
} dos={ -
-
    -
  • Use a SwatchColorPicker when there are multiple finite choices that can be grouped and/or collapsed under one title.
    • -
  • SwatchColorPickers contain a grid of colors.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerDos.md') } + } donts={ -
-
    -
  • Do not use a SwatchColorPicker when there are a a very large number of color choices. The best component for to that is a ColorPicker.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Spinner/docs/SpinnerDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDonts.md b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDonts.md new file mode 100644 index 00000000000000..6520df00b232bb --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDonts.md @@ -0,0 +1 @@ +- Do not use a SwatchColorPicker when there are a a very large number of color choices. The best component for to that is a ColorPicker. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDos.md b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDos.md new file mode 100644 index 00000000000000..7c7632931d36f4 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerDos.md @@ -0,0 +1,2 @@ +- Use a SwatchColorPicker when there are multiple finite choices that can be grouped and/or collapsed under one title. +- SwatchColorPickers contain a grid of colors. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerOverview.md b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerOverview.md new file mode 100644 index 00000000000000..bf7c8218c478e1 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/SwatchColorPicker/docs/SwatchColorPickerOverview.md @@ -0,0 +1 @@ +A SwatchColorPicker is a list of colors displayed as a grid as options for the user. It can be displayed by itself, with header and/or dividers, or as a button which expands to show the swatch color picker. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubblePage.tsx b/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubblePage.tsx index 10b1490033ca66..4e6fa55136ac1b 100644 --- a/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubblePage.tsx +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubblePage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { TeachingBubbleBasicExample } from './examples/TeachingBubble.Basic.Example'; @@ -26,6 +27,7 @@ export class TeachingBubblePage extends React.Component @@ -53,14 +55,14 @@ export class TeachingBubblePage extends React.Component } overview={ -
-

TeachingBubbles allow the user to display important hints on their web pages with a callout box.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md new file mode 100644 index 00000000000000..3f69fd9d5b86b1 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md @@ -0,0 +1 @@ +TeachingBubbles allow the user to display important hints on their web pages with a callout box. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/TextField/TextFieldPage.tsx b/packages/office-ui-fabric-react/src/components/TextField/TextFieldPage.tsx index 15ebbbd00d5196..b53950817af652 100644 --- a/packages/office-ui-fabric-react/src/components/TextField/TextFieldPage.tsx +++ b/packages/office-ui-fabric-react/src/components/TextField/TextFieldPage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus'; @@ -39,6 +40,7 @@ export class TextFieldPage extends React.Component /> } overview={ -
-

- The TextField component enables a user to type text into an app. It's typically used to capture a single line of text, but can be configured to capture multiple lines of text. The text displays on the screen in a simple, uniform format. -

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/TextField/docs/TextFieldOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • Use the TextField to accept data input on a form or page.
    • -
  • Label the TextField with a helpful name.
    • -
  • Provide concise helper text that specifies what content is expected to be entered.
    • -
  • Provide all appropriate states for the control (static, hover, focus, engaged, unavailable, error).
    • -
  • When part of a form, provide clear designations for which fields are required vs. optional.
    • -
  • Provide all appropriate methods for submitting provided data (onEnter or a dedicated ‘Submit’ button).
    • -
  • Provide all appropriate methods of clearing provided data (‘X’ or something similar).
    • -
  • Allow for selection, copy and paste of field data.
    • -
  • Whenever possible, format TextField relative to the expected entry (4-digit PIN, 10-digit phone number (3 separate fields), etc).
    • -
  • When long entries are expected, provide a mechanism for overflow or expansion of the control itself.
    • -
  • Ensure that the TextField is functional through use of mouse/keyboard or touch when available.
    • -
  • Ensure that the TextField is accessible through screen reader and/or other accessibility tools.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/TextField/docs/TextFieldDos.md') } + } donts={ -
-
    -
  • Don’t use a TextField to render basic copy as part of a body element of a page.
    • -
  • Don’t provide an unlabeled TextField and expect that users will know what to do with it.
    • -
  • Don’t place a TextField inline with body copy.
    • -
  • Don’t be overly verbose with helper text.
    • -
  • Don’t occlude the entry or allow entry when the active content is not visible.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/TextField/docs/TextFieldDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDonts.md b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDonts.md new file mode 100644 index 00000000000000..0e922b792ca5d0 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDonts.md @@ -0,0 +1,5 @@ +- Don’t use a TextField to render basic copy as part of a body element of a page. +- Don’t provide an unlabeled TextField and expect that users will know what to do with it. +- Don’t place a TextField inline with body copy. +- Don’t be overly verbose with helper text. +- Don’t occlude the entry or allow entry when the active content is not visible. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDos.md b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDos.md new file mode 100644 index 00000000000000..3d14cce44df2cd --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldDos.md @@ -0,0 +1,12 @@ +- Use the TextField to accept data input on a form or page. +- Label the TextField with a helpful name. +- Provide concise helper text that specifies what content is expected to be entered. +- Provide all appropriate states for the control (static, hover, focus, engaged, unavailable, error). +- When part of a form, provide clear designations for which fields are required vs. optional. +- Provide all appropriate methods for submitting provided data (onEnter or a dedicated ‘Submit’ button). +- Provide all appropriate methods of clearing provided data (‘X’ or something similar). +- Allow for selection, copy and paste of field data. +- Whenever possible, format TextField relative to the expected entry (4-digit PIN, 10-digit phone number (3 separate fields), etc). +- When long entries are expected, provide a mechanism for overflow or expansion of the control itself. +- Ensure that the TextField is functional through use of mouse/keyboard or touch when available. +- Ensure that the TextField is accessible through screen reader and/or other accessibility tools. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldOverview.md b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldOverview.md new file mode 100644 index 00000000000000..2c19bb3bb700d4 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TextField/docs/TextFieldOverview.md @@ -0,0 +1 @@ +The TextField component enables a user to type text into an app. It's typically used to capture a single line of text, but can be configured to capture multiple lines of text. The text displays on the screen in a simple, uniform format. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Theme/ThemePage.scss b/packages/office-ui-fabric-react/src/components/Theme/ThemePage.scss deleted file mode 100644 index 423e2396245867..00000000000000 --- a/packages/office-ui-fabric-react/src/components/Theme/ThemePage.scss +++ /dev/null @@ -1,30 +0,0 @@ -@import '../../common/common'; - -:global { - - .Themes { - padding: 40px; - } - - .ThemePage-colorSwatch { - @include focus-border(); - margin: -10px 0; - line-height: 36px; - white-space: nowrap; - cursor: pointer; - - &:hover { - background: rgba(0,0,0,.05); - } - } - - .ThemePage-swatch { - display: inline-block; - width: 36px; - height: 36px; - vertical-align: middle; - @include ms-margin-right(5px); - border: 1px solid rgba(127, 127, 127, .5); - } - -} \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Theme/ThemePage.styles.ts b/packages/office-ui-fabric-react/src/components/Theme/ThemePage.styles.ts new file mode 100644 index 00000000000000..216e30099d13fa --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Theme/ThemePage.styles.ts @@ -0,0 +1,43 @@ +import { IThemePageStyleProps, IThemePageStyles } from './ThemePage.types'; +import { + getFocusStyle, + getTheme, +} from '../../Styling'; + +export const getStyles = ( + props: IThemePageStyleProps +): IThemePageStyles => { + const theme = getTheme(); + return ({ + colorSwatch: [ + 'ThemePage-colorSwatch', + getFocusStyle(theme), + { + margin: '-10px 0', + lineHeight: '36px', + whiteSpace: 'nowrap', + cursor: 'pointer', + + selectors: { + ':hover': { + background: 'rgba(0,0,0,.05)', + } + } + } + ], + + swatch: [ + 'ThemePage-swatch', + { + display: 'inline-block', + width: '36px', + height: '36px', + verticalAlign: 'middle', + marginRight: '5px', + border: '1px solid rgba(127, 127, 127, .5)', + } + ], + + colorValue: 'ThemePage-colorValue', + }); +}; diff --git a/packages/office-ui-fabric-react/src/components/Theme/ThemePage.tsx b/packages/office-ui-fabric-react/src/components/Theme/ThemePage.tsx index fea63772c11c85..70009969c39495 100644 --- a/packages/office-ui-fabric-react/src/components/Theme/ThemePage.tsx +++ b/packages/office-ui-fabric-react/src/components/Theme/ThemePage.tsx @@ -1,111 +1,142 @@ import * as React from 'react'; -import { loadTheme, FontClassNames, IPalette } from 'office-ui-fabric-react/lib/Styling'; -import { IComponentDemoPageProps, Highlight } from '@uifabric/example-app-base'; -import { defaultTheme } from './defaultTheme'; -import { Callout } from 'office-ui-fabric-react/lib/Callout'; -import { DetailsList, DetailsListLayoutMode as LayoutMode } from 'office-ui-fabric-react/lib/DetailsList'; -import { SelectionMode } from 'office-ui-fabric-react/lib/Selection'; -import { ColorPicker } from 'office-ui-fabric-react/lib/ColorPicker'; -import './ThemePage.scss'; -const ThemeCodeExample = require('!raw-loader!office-ui-fabric-react/src/components/Theme/examples/ThemeCode.Example.tsx'); - -export class ThemePage extends React.Component { +import { + classNamesFunction, + customizable, +} from '../../Utilities'; +import { + FontClassNames, + IPalette, + ISemanticColors, + loadTheme, +} from '../../Styling'; +import { + ComponentPage, + Highlight, + IComponentDemoPageProps, + PageMarkdown, +} from '@uifabric/example-app-base'; +import { + IThemePagePalette, + IThemePageStyleProps, + IThemePageStyles, + IThemePageState, +} from './ThemePage.types'; +import { + defaultPalette, + defaultSemanticColors, +} from './defaultTheme'; +import { getStyles } from './ThemePage.styles'; +import { Callout } from '../Callout'; +import { DetailsList, DetailsListLayoutMode } from '../../DetailsList'; +import { SelectionMode } from '../../Selection'; +import { ColorPicker } from '../ColorPicker'; + +const getClassNames = classNamesFunction(); + +export class ThemePage extends React.Component { private _list: DetailsList; - constructor(props: {}) { + constructor(props: IComponentDemoPageProps) { super(props); this._onPickerDismiss = this._onPickerDismiss.bind(this); this.state = { - colors: Object.keys(defaultTheme).map(variableName => ({ - key: variableName, - name: variableName, - value: (defaultTheme as any)[variableName], - description: '', - colorPickerProps: undefined - })) + palette: defaultPalette, + semanticColors: defaultSemanticColors, }; } public render() { - const { colors, colorPickerProps } = this.state; + // Don't mutate state to display lists + const palette = [...this.state.palette]; + const semanticColors = [...this.state.semanticColors]; + return ( + + { require('!raw-loader!office-ui-fabric-react/src/components/Theme/docs/ThemesOverview.md') } + + } + otherSections={ [ + { + title: 'Default Palette', + section: this._colorList(palette, 'palette') + }, + { + title: 'Default Semantic Colors', + section: this._colorList(semanticColors, 'semanticColors') + }, + ] } + isHeaderVisible={ this.props.isHeaderVisible } + /> + ); + } + private _colorList = (colors: any, list: 'palette' | 'semanticColors') => { + const classNames = getClassNames(getStyles); + const { colorPickerProps } = this.state; return ( -
-

Themes

-

The entire color palette of the controls are themeable. We provide a set of sensible defaults, but you can override all colors individually.

-

To override the themes, you need to call loadTheme() with the appropriate set of overrides:

- - - { ThemeCodeExample } - - -

Define a theme

-
- ( -
- - { item.value } -
- ) - }, - { - key: 'desc', - name: 'Description', - fieldName: 'description', - minWidth: 90 - } - ] } - /> - - { colorPickerProps && ( - - - - - - ) } - -
+
+ ( +
+ + { item.value } +
+ ) + }, + { + key: 'desc', + name: 'Description', + fieldName: 'description', + minWidth: 90 + } + ] } + /> + + { colorPickerProps && ( + + + + + + ) }
); @@ -115,33 +146,47 @@ export class ThemePage extends React.Component) { + private _onSwatchClicked(item: any, index: number, list: string, ev: React.MouseEvent) { this.setState({ colorPickerProps: { targetElement: (ev.currentTarget as HTMLElement).children[0] as HTMLElement, value: item.value, - index: index - } + index: index, + }, + activeList: list }); } private _onColorChanged(index: number, newColor: string) { - const { colors } = this.state; - const color = colors[index]; - const palette: Partial = {}; - - color.value = newColor; - - for (let i = 0; i < colors.length; i++) { - const themeColor = colors[i]; - - (palette as any)[themeColor.key] = themeColor.value; + const { activeList } = this.state; + const partialPalette: Partial = {}; + const partialSemanticColors: Partial = {}; + + if (activeList === 'palette') { + const palette = [...this.state.palette]; + const paletteColor = palette[index]; + paletteColor.value = newColor; + palette[index] = paletteColor; + for (let i = 0; i < palette.length; i++) { + (palette as any)[palette[i].key] = palette[i].value; + } + } else if (activeList === 'semanticColors') { + const semanticColors = [...this.state.semanticColors]; + const semanticColor = semanticColors[index]; + semanticColor.value = newColor; + semanticColors[index] = semanticColor; + for (let i = 0; i < semanticColors.length; i++) { + (semanticColors as any)[semanticColors[i].key] = semanticColors[i].value; + } + } else { + this.setState({ activeList: undefined }); + return undefined; } - loadTheme({ palette }); + this.setState({ activeList: undefined }); + const partialTheme = { ...partialPalette, ...partialSemanticColors }; - // The theme has changed values, but color state is the same. Force an update on the list. - this._list.forceUpdate(); + loadTheme({ palette: partialTheme }); } private _onPickerDismiss() { @@ -149,5 +194,4 @@ export class ThemePage extends React.Component ({ + key: variableName, + name: variableName, + value: (defaultTheme.palette as any)[variableName], + description: '', +})); + +export const defaultSemanticColors = Object.keys(defaultTheme.semanticColors).map(variableName => ({ + key: variableName, + name: variableName, + value: (defaultTheme.semanticColors as any)[variableName], + description: (defaultTheme.semanticColors as any)[variableName].indexOf('@deprecated') >= 0 ? 'Deprecated' : '', +})); diff --git a/packages/office-ui-fabric-react/src/components/Theme/docs/ThemesOverview.md b/packages/office-ui-fabric-react/src/components/Theme/docs/ThemesOverview.md new file mode 100644 index 00000000000000..b117ba5ddd0bb9 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Theme/docs/ThemesOverview.md @@ -0,0 +1,33 @@ +The entire color palette of the controls are themeable. We provide a set of sensible defaults, but you can override all colors individually. + +## Loading Themes + +To load the theme call `getTheme()`. This returns an object with all the colors and fonts set in the current theme: + +```tsx +let myTheme = getTheme(); + +// returns: +myTheme = { + palette: {...}, // All the palette colors + semanticColors: {...}, // All the semanticColors + fonts: {...}, // All the font stacks like small, medium, large, etc + isInverted: false // Boolean of whether the theme is currently inverted +} +``` + +Using `getTheme(true)` will add comments to deprecated semanticColors. + +## Overriding Themes + +To override the themes, you need to call `loadTheme()` with the appropriate set of overrides: + +```tsx +import { loadTheme } from 'office-ui-fabric-react/lib/Styling'; + +loadTheme({ + palette: { + 'themePrimary': 'red' + } +}); +``` \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Theme/examples/ThemeCode.Example.tsx b/packages/office-ui-fabric-react/src/components/Theme/examples/ThemeCode.Example.tsx deleted file mode 100644 index 8889c8b957c5aa..00000000000000 --- a/packages/office-ui-fabric-react/src/components/Theme/examples/ThemeCode.Example.tsx +++ /dev/null @@ -1,7 +0,0 @@ -import { loadTheme } from 'office-ui-fabric-react/lib/Styling'; - -loadTheme({ - palette: { - 'themePrimary': 'red' - } -}); diff --git a/packages/office-ui-fabric-react/src/components/Toggle/TogglePage.tsx b/packages/office-ui-fabric-react/src/components/Toggle/TogglePage.tsx index 2373ebbf3031bf..85f916823701c7 100644 --- a/packages/office-ui-fabric-react/src/components/Toggle/TogglePage.tsx +++ b/packages/office-ui-fabric-react/src/components/Toggle/TogglePage.tsx @@ -3,6 +3,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { ToggleBasicExample } from './examples/Toggle.Basic.Example'; @@ -20,6 +21,7 @@ export class TogglePage extends React.Component { { /> } overview={ -
-

- Toggles represent a physical switch that allows users to turn things on or off. Use Toggles to present users with two mutually exclusive options (like on/off), where choosing an option results in an immediate action. Use a Toggle for binary operations that take effect right after the user flips the Toggle. For example, use a Toggle to turn services or hardware components on or off. In other words, if a physical switch would work for the action, a Toggle is probably the best control to use. -

- -

Choosing between Toggle and Checkbox

- -

- For some actions, either a Toggle or a Checkbox might work. To decide which control would work better, follow these tips: -

- -
    -
  • Use a Toggle for binary settings when changes become effective immediately after the user changes them.
    • -
  • In the above example, it's clear with the Toggle that the wireless is set to "On." But with the Checkbox, the user needs to think about whether the wireless is on now or whether they need to check the box to turn wireless on.
    • -
  • Use a Checkbox when the user has to perform extra steps for changes to be effective. For example, if the user must click a "Submit", "Next", "Ok" button to apply changes, use a Checkbox.
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Toggle/docs/ToggleOverview.md') } + } bestPractices={
} dos={ -
-
    -
  • - Only replace the On and Off labels if there are more specific labels for the setting. If there are short (3-4 characters) labels that represent binary opposites that are more appropriate for a particular setting, use them. For example, you might use "Show/Hide" if the setting is "Show images." -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Toggle/docs/ToggleDos.md') } + } donts={ -
-
    - Don’t use a Toggle if the user will have to do something else or go somewhere else in order to experience its effect. If any extra step is required for changes to be effective, you should use a checkbox and corresponding "Apply" button instead of a Toggle. -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Toggle/docs/ToggleDonts.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDonts.md b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDonts.md new file mode 100644 index 00000000000000..c23d5922234655 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDonts.md @@ -0,0 +1 @@ +- Don’t use a Toggle if the user will have to do something else or go somewhere else in order to experience its effect. If any extra step is required for changes to be effective, you should use a checkbox and corresponding "Apply" button instead of a Toggle. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDos.md b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDos.md new file mode 100644 index 00000000000000..50e927ea935b9b --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleDos.md @@ -0,0 +1 @@ +- Only replace the On and Off labels if there are more specific labels for the setting. If there are short (3-4 characters) labels that represent binary opposites that are more appropriate for a particular setting, use them. For example, you might use "Show/Hide" if the setting is "Show images." \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleOverview.md b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleOverview.md new file mode 100644 index 00000000000000..ff7eb45edd0698 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Toggle/docs/ToggleOverview.md @@ -0,0 +1,9 @@ +Toggles represent a physical switch that allows users to turn things on or off. Use Toggles to present users with two mutually exclusive options (like on/off), where choosing an option results in an immediate action. Use a Toggle for binary operations that take effect right after the user flips the Toggle. For example, use a Toggle to turn services or hardware components on or off. In other words, if a physical switch would work for the action, a Toggle is probably the best control to use. + +## Choosing between Toggle and Checkbox + +For some actions, either a Toggle or a Checkbox might work. To decide which control would work better, follow these tips: + +- Use a Toggle for binary settings when changes become effective immediately after the user changes them. +- In the above example, it's clear with the Toggle that the wireless is set to "On." But with the Checkbox, the user needs to think about whether the wireless is on now or whether they need to check the box to turn wireless on. +- Use a Checkbox when the user has to perform extra steps for changes to be effective. For example, if the user must click a "Submit", "Next", "Ok" button to apply changes, use a Checkbox. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/Tooltip/TooltipPage.tsx b/packages/office-ui-fabric-react/src/components/Tooltip/TooltipPage.tsx index d0dea1e316a5d1..3b90b2881970ca 100644 --- a/packages/office-ui-fabric-react/src/components/Tooltip/TooltipPage.tsx +++ b/packages/office-ui-fabric-react/src/components/Tooltip/TooltipPage.tsx @@ -5,6 +5,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { TooltipCustomExample } from './examples/Tooltip.Custom.Example'; @@ -27,6 +28,7 @@ export class TooltipPage extends React.Component { @@ -56,11 +58,9 @@ export class TooltipPage extends React.Component { /> } overview={ -
-

Tooltips supplement content associated with a specific UI component. You can use two components, and each has different props:

-

Tooltip: A styled tooltip that you can display on a chosen target.

-

TooltipHost: A tooltip wrapped in a stateful parent. Tooltip will be displayed on hover or focus and removed when focus/hover removed.

-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/Tooltip/docs/TooltipOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ diff --git a/packages/office-ui-fabric-react/src/components/Tooltip/docs/TooltipOverview.md b/packages/office-ui-fabric-react/src/components/Tooltip/docs/TooltipOverview.md new file mode 100644 index 00000000000000..1b62158e8b11d2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/Tooltip/docs/TooltipOverview.md @@ -0,0 +1,4 @@ +Tooltips supplement content associated with a specific UI component. You can use two components, and each has different props: + +- **Tooltip:** A styled tooltip that you can display on a chosen target. +- **TooltipHost:** A tooltip wrapped in a stateful parent. Tooltip will be displayed on hover or focus and removed when focus/hover removed. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/PeoplePickerPage.tsx b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/PeoplePickerPage.tsx index 1a48eb28b8d41d..ed00e5de897055 100644 --- a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/PeoplePickerPage.tsx +++ b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/PeoplePickerPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { PeoplePickerTypesExample } from './examples/PeoplePicker.Types.Example'; @@ -18,6 +19,7 @@ export class PeoplePickerPage extends React.Component @@ -33,37 +35,29 @@ export class PeoplePickerPage extends React.Component } overview={ -
- PeoplePicker - are used to pick recipients. -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerOverview.md') } + } - isHeaderVisible={ this.props.isHeaderVisible } bestPractices={ -
The PeoplePicker is used to select one or more entities, such as people or groups. Entry points for PeoplePickers are typically specialized TextField-like input fields known as a "well", which are used to search for recipients from a list. When a recipient is selected from the list, it is added to the well as a specialized Persona that can be interacted with or removed. Clicking on a Persona from the well should invoke a PersonaCard or open a profile pane for that recipient.
+ + { require('!raw-loader!office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerBestPractices.md') } + } dos={ -
-
    -
  • Use the PeoplePicker to quickly search for a few people
    • -
  • Use the PeoplePicker to manage a group of people
    • -
  • Use the MemberList PeoplePicker to display selections below the input box
    • -
  • Use defaultSelectedItems when some people have already been selected
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDos.md') } + } donts={ -
-
    -
  • Use the PeoplePicker to select something other than people
    • -
  • Use the PeoplePicker to only display people
    • -
  • Use the PeoplePicker without sufficient space
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDonts.md') } + } + isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerBestPractices.md b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerBestPractices.md new file mode 100644 index 00000000000000..cb03a88771a89f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerBestPractices.md @@ -0,0 +1 @@ +The PeoplePicker is used to select one or more entities, such as people or groups. Entry points for PeoplePickers are typically specialized TextField-like input fields known as a "well", which are used to search for recipients from a list. When a recipient is selected from the list, it is added to the well as a specialized Persona that can be interacted with or removed. Clicking on a Persona from the well should invoke a PersonaCard or open a profile pane for that recipient. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDonts.md b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDonts.md new file mode 100644 index 00000000000000..48856a3612fc87 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDonts.md @@ -0,0 +1,3 @@ +- Use the PeoplePicker to select something other than people +- Use the PeoplePicker to only display people +- Use the PeoplePicker without sufficient space \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDos.md b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDos.md new file mode 100644 index 00000000000000..473ac1a8f39cc2 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerDos.md @@ -0,0 +1,4 @@ +- Use the PeoplePicker to quickly search for a few people +- Use the PeoplePicker to manage a group of people +- Use the MemberList PeoplePicker to display selections below the input box +- Use defaultSelectedItems when some people have already been selected \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerOverview.md b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerOverview.md new file mode 100644 index 00000000000000..63fc62c42dbf4f --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/pickers/PeoplePicker/docs/PeoplePickerOverview.md @@ -0,0 +1 @@ + PeoplePickers are used to pick recipients. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/pickers/PickersPage.tsx b/packages/office-ui-fabric-react/src/components/pickers/PickersPage.tsx index 218833888421ef..e6251d7dbb91a5 100644 --- a/packages/office-ui-fabric-react/src/components/pickers/PickersPage.tsx +++ b/packages/office-ui-fabric-react/src/components/pickers/PickersPage.tsx @@ -4,6 +4,7 @@ import { ExampleCard, ComponentPage, IComponentDemoPageProps, + PageMarkdown, PropertiesTableSet } from '@uifabric/example-app-base'; import { PickerCustomResultExample } from './examples/Picker.CustomResult.Example'; @@ -20,6 +21,7 @@ export class PickersPage extends React.Component { @@ -38,15 +40,14 @@ export class PickersPage extends React.Component { /> } overview={ -
- Pickers - are used to pick recipients. -
+ + { require('!raw-loader!office-ui-fabric-react/src/components/pickers/docs/PickersOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } componentStatus={ } /> diff --git a/packages/office-ui-fabric-react/src/components/pickers/docs/PickersOverview.md b/packages/office-ui-fabric-react/src/components/pickers/docs/PickersOverview.md new file mode 100644 index 00000000000000..6d96036aa25cbf --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/pickers/docs/PickersOverview.md @@ -0,0 +1 @@ + Pickers are used to pick recipients. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/demo/ComponentStatus/ComponentStatusPage.tsx b/packages/office-ui-fabric-react/src/demo/ComponentStatus/ComponentStatusPage.tsx index f8711dae7a53ba..a9bfde92f31126 100644 --- a/packages/office-ui-fabric-react/src/demo/ComponentStatus/ComponentStatusPage.tsx +++ b/packages/office-ui-fabric-react/src/demo/ComponentStatus/ComponentStatusPage.tsx @@ -1,5 +1,9 @@ import * as React from 'react'; -import { ComponentPage, IComponentPageSection } from '@uifabric/example-app-base'; +import { + ComponentPage, + IComponentPageSection, + PageMarkdown, +} from '@uifabric/example-app-base'; import { Link } from '../../Link'; import { AllComponentsStatus } from './AllComponents.checklist'; import { ComponentStatusInfoState, IComponentStatusInfoState, InformationLink } from './ComponentStatusState'; @@ -14,6 +18,7 @@ export class ComponentStatusPage extends React.Component<{}, {}> { @@ -22,9 +27,9 @@ export class ComponentStatusPage extends React.Component<{}, {}> { private _renderOverView(): JSX.Element { return ( -
- Badges are used to track a component's status regarding different criteria. They reflect if a component is localizable, accessible and reliable. -
+ + { require('!raw-loader!office-ui-fabric-react/src/demo/ComponentStatus/docs/ComponentChecklistOverview.md') } + ); } diff --git a/packages/office-ui-fabric-react/src/demo/ComponentStatus/docs/ComponentChecklistOverview.md b/packages/office-ui-fabric-react/src/demo/ComponentStatus/docs/ComponentChecklistOverview.md new file mode 100644 index 00000000000000..b5e19a2e80c92a --- /dev/null +++ b/packages/office-ui-fabric-react/src/demo/ComponentStatus/docs/ComponentChecklistOverview.md @@ -0,0 +1 @@ +Badges are used to track a component's status regarding different criteria. They reflect if a component is localizable, accessible and reliable. \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/demo/GettingStartedPage.scss b/packages/office-ui-fabric-react/src/demo/GettingStartedPage.scss index 61cd171c17c190..563450d8887281 100644 --- a/packages/office-ui-fabric-react/src/demo/GettingStartedPage.scss +++ b/packages/office-ui-fabric-react/src/demo/GettingStartedPage.scss @@ -24,13 +24,18 @@ margin: -20px; margin-bottom: 20px; border-bottom: 1px solid $ms-color-neutralTertiaryAlt; - - h1 { - margin-bottom: 0; - } - - h3 { - margin-top: 0; + display: flex; + align-items: center; + justify-content: space-between; + + .ms-GettingStartedPage-title { + h1 { + margin-bottom: 0; + } + + h3 { + margin-top: 0; + } } } diff --git a/packages/office-ui-fabric-react/src/demo/GettingStartedPage.tsx b/packages/office-ui-fabric-react/src/demo/GettingStartedPage.tsx index 2aeff4d2bd5573..36685a53e5183c 100644 --- a/packages/office-ui-fabric-react/src/demo/GettingStartedPage.tsx +++ b/packages/office-ui-fabric-react/src/demo/GettingStartedPage.tsx @@ -2,88 +2,43 @@ import * as React from 'react'; import { Link } from 'office-ui-fabric-react/lib/Link'; +import { IconButton } from 'office-ui-fabric-react/lib/Button'; +import { TooltipHost } from 'office-ui-fabric-react/lib/Tooltip'; import './GettingStartedPage.scss'; -import { Highlight } from '@uifabric/example-app-base'; +import { Highlight, PageMarkdown } from '@uifabric/example-app-base'; export class GettingStartedPage extends React.Component { public render() { return (
-
-

office-ui-fabric-react

-

A library of reusable, generic React components

-
- -

Overview

- -

{ - `Fabric React components are built as production ready components to be used in Microsoft products, but generalized, documented, and reusable. This enables us and our partners to more easily build great applications without spending a ton of time implementing the same things over and over.` - }

- -

{ - `Each component is designed to be RTL friendly, keyboard accessible, screen reader friendly, themeable, and generalized. TypeScript definition files are also included, so if you use TypeScript (which isn't a requirement), you will get compiler validation and using an editor like VS Code, you'll get intellisense. Each component is exported as a named module that can be easily imported in your code, allowing your external bundler to create small bundles that include just what you need.` - }

- -

Getting started

- -

{ `Integrating components into your project depends heavily on your setup. The recommended setup is to use a bundler such as ` }Webpack{ ` which can resolve NPM package imports in your code and can bundle the specific things you import.` }

- -

{ - `Within an npm project, you should install the package and save it as a dependency:` - }

- -
- npm install --save office-ui-fabric-react +
+

office-ui-fabric-react

+

A library of reusable, generic React components

+
+ { this._getEditButton() }
- -

{ - `This will add the fabric-react project as a dependency in your package.json file, and will drop the project under node_modules/office-ui-fabric-react.` - }

- -

{ - `The library includes commonjs entry points under the lib folder. To use a control, you should be able to import it and use it in your render method. Note that wrapping your application in the Fabric component is required to support RTL, keyboard focus and other features.` - }

- -
- { - `import * as React from 'react'; -import * as ReactDOM from 'react-dom'; -import { Fabric } from 'office-ui-fabric-react/lib/Fabric'; -import { DefaultButton } from 'office-ui-fabric-react/lib/Button'; - -const MyPage = () => (I am a button.); - -ReactDOM.render(, document.body.firstChild);` - } -
- -

Notes on module vs path-based imports

-

{ - `While it is possible to import all components as named imports from the main module entry point, it is not recommended to do so without using a bundler that supports es6 tree shaking. In other words, if you import the Button component like this:` - }

- -
- { `import { Button } from 'office-ui-fabric-react';` } -
- -

{ `...this would work, but then unless you are using a tree-shaking bundler such as Rollup.js or Webpack 2, Webpack will assume you want every module exported from the main entry file to be included in your final bundle, which produces unnecessary large bundles and slows your page load down. Instead you can import the specific paths to trim down your bundle size:` }

- -
- { - `import { Button } from 'office-ui-fabric-react/lib/Button'; -import { Dropdown } from 'office-ui-fabric-react/lib/Dropdown'; -import { List } from 'office-ui-fabric-react/lib/List';` - } -
- -

Using an AMD bundler like r.js

- -

{ ` - If your project relies on AMD modules, they are dropped in the lib-amd folder. You will need to set up your bundler to handle the imports correctly. This may require you to symlink or copy the folder into your pre-bundle location. - ` }

- + + { require('!raw-loader!office-ui-fabric-react/src/demo/docs/GettingStartedOverview.md') } +
); } + private _getEditButton() { + return ( + + + + ); + } } diff --git a/packages/office-ui-fabric-react/src/demo/docs/GettingStartedOverview.md b/packages/office-ui-fabric-react/src/demo/docs/GettingStartedOverview.md new file mode 100644 index 00000000000000..b6f017e271d9a3 --- /dev/null +++ b/packages/office-ui-fabric-react/src/demo/docs/GettingStartedOverview.md @@ -0,0 +1,52 @@ +## Overview + +Fabric React components are built as production ready components to be used in Microsoft products, but generalized, documented, and reusable. This enables us and our partners to more easily build great applications without spending a ton of time implementing the same things over and over. + +Each component is designed to be RTL friendly, keyboard accessible, screen reader friendly, themeable, and generalized. TypeScript definition files are also included, so if you use TypeScript (which isn't a requirement), you will get compiler validation and using an editor like VS Code, you'll get intellisense. Each component is exported as a named module that can be easily imported in your code, allowing your external bundler to create small bundles that include just what you need. + +## Getting Started + +Integrating components into your project depends heavily on your setup. The recommended setup is to use a bundler such as Webpack which can resolve NPM package imports in your code and can bundle the specific things you import. + +Within an npm project, you should install the package and save it as a dependency: + +```bash +npm install --save office-ui-fabric-react +``` + +This will add the fabric-react project as a dependency in your package.json file, and will drop the project under node_modules/office-ui-fabric-react. + +The library includes commonjs entry points under the lib folder. To use a control, you should be able to import it and use it in your render method. Note that wrapping your application in the Fabric component is required to support RTL, keyboard focus and other features. + +```tsx +import * as React from 'react'; +import * as ReactDOM from 'react-dom'; +import { Fabric } from 'office-ui-fabric-react/lib/Fabric'; +import { DefaultButton } from 'office-ui-fabric-react/lib/Button'; + +const MyPage = () => (I am a button.); + +ReactDOM.render(, document.body.firstChild); +``` + +## Notes on module vs path-based imports + +While it is possible to import all components as named imports from the main module entry point, it is not recommended to do so without using a bundler that supports es6 tree shaking. In other words, if you import the Button component like this: + +```tsx +import { Button } from 'office-ui-fabric-react'; +``` + +...this would work, but then unless you are using a tree-shaking bundler such as Rollup.js or Webpack 2, Webpack will assume you want every module exported from the main entry file to be included in your final bundle, which produces unnecessary large bundles and slows your page load down. Instead you can import the specific paths to trim down your bundle size: + +```tsx +import { Button } from 'office-ui-fabric-react/lib/Button'; +import { Dropdown } from 'office-ui-fabric-react/lib/Dropdown'; +import { List } from 'office-ui-fabric-react/lib/List'; +``` + +## Using an AMD bundler like r.js + +If your project relies on AMD modules, they are dropped in the lib-amd folder. You will need to set up your bundler to handle the imports correctly. This may require you to symlink or copy the folder into your pre-bundle location. + +
\ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/utilities/selection/SelectionPage.tsx b/packages/office-ui-fabric-react/src/utilities/selection/SelectionPage.tsx index 7eae905e116b1a..2c5ccb1fe90645 100644 --- a/packages/office-ui-fabric-react/src/utilities/selection/SelectionPage.tsx +++ b/packages/office-ui-fabric-react/src/utilities/selection/SelectionPage.tsx @@ -2,6 +2,7 @@ import * as React from 'react'; import { ExampleCard, ComponentPage, + PageMarkdown, IComponentDemoPageProps } from '@uifabric/example-app-base'; @@ -15,43 +16,16 @@ export class SelectionPage extends React.Component } overview={ -
-

- Selection is a store that maintains the selection state of items in an efficient way. - It exposes methods for accessing the selection state given an item index. - If the items change, it can resolve the selection if items move in the array. -

- -

SelectionZone is a React component that acts as a mediator between the Selection object and elements. By providing it the Selection instance and rendering content within it, you can have it manage clicking/focus/keyboarding from the DOM and translate into selection updates. You just need to provide the right data-selection-* attributes on elements within each row/tile to give SelectionZone a hint what the intent is.

- -

SelectionZone also takes in an onItemInvoked callback for when items are invoked. Invoking occurs when a user double clicks a row, presses enter while focused on it, or clicks within an element marked by the data-selection-invoke attribute. -

- -

Available attributes:

-
    -
  • - data-selection-index: the index of the item being represented.This would go on the root of the tile/row. -
    • -
  • - data-selection-invoke: this boolean flag would be set on the element which should immediately invoke the item on click.There is also a nuanced behavior where we will clear selection and select the item if mousedown occurs on an unselected item. -
    • -
  • - data-selection-toggle: this boolean flag would be set on the element which should handle toggles.This could be a checkbox or a div. -
    • -
  • - data-selection-toggle-all: this boolean flag indicates that clicking it should toggle all selection. -
    • -
  • - data-selection-disabled: allows a branch of the DOM to be marked to ignore input events that alter selections. -
    • -
-
+ + { require('!raw-loader!office-ui-fabric-react/src/utilities/selection/docs/SelectionOverview.md') } + } isHeaderVisible={ this.props.isHeaderVisible } /> diff --git a/packages/office-ui-fabric-react/src/utilities/selection/docs/SelectionOverview.md b/packages/office-ui-fabric-react/src/utilities/selection/docs/SelectionOverview.md new file mode 100644 index 00000000000000..fe073967737dbf --- /dev/null +++ b/packages/office-ui-fabric-react/src/utilities/selection/docs/SelectionOverview.md @@ -0,0 +1,15 @@ +Selection is a store that maintains the selection state of items in an efficient way. +It exposes methods for accessing the selection state given an item index. +If the items change, it can resolve the selection if items move in the array. + +SelectionZone is a React component that acts as a mediator between the Selection object and elements. By providing it the Selection instance and rendering content within it, you can have it manage clicking/focus/keyboarding from the DOM and translate into selection updates. You just need to provide the right data-selection-* attributes on elements within each row/tile to give SelectionZone a hint what the intent is. + +SelectionZone also takes in an onItemInvoked callback for when items are invoked. Invoking occurs when a user double clicks a row, presses enter while focused on it, or clicks within an element marked by the data-selection-invoke attribute. + +Available attributes: + +- **data-selection-index:** the index of the item being represented.This would go on the root of the tile/row. +- **data-selection-invoke:** this boolean flag would be set on the element which should immediately invoke the item on click.There is also a nuanced behavior where we will clear selection and select the item if mousedown occurs on an unselected item. +- **data-selection-toggle:** this boolean flag would be set on the element which should handle toggles.This could be a checkbox or a div. +- **data-selection-toggle-all:** this boolean flag indicates that clicking it should toggle all selection. +- **data-selection-disabled:** allows a branch of the DOM to be marked to ignore input events that alter selections. diff --git a/packages/styling/src/styles/theme.ts b/packages/styling/src/styles/theme.ts index 2611df309824f9..ab52c951ba3df2 100644 --- a/packages/styling/src/styles/theme.ts +++ b/packages/styling/src/styles/theme.ts @@ -15,7 +15,7 @@ import { loadTheme as legacyLoadTheme } from '@microsoft/load-themed-styles'; let _theme: ITheme = { palette: DefaultPalette, - semanticColors: _makeSemanticColorsFromPalette(DefaultPalette, false), + semanticColors: _makeSemanticColorsFromPalette(DefaultPalette, false, false), fonts: DefaultFontStyles, isInverted: false }; @@ -37,9 +37,13 @@ if (!Customizations.getSettings([ThemeSettingName]).theme) { } /** - * Gets the theme object. + * Gets the theme object + * @param {boolean} depComments - Whether to include deprecated tags as comments for deprecated slots. */ -export function getTheme(): ITheme { +export function getTheme(depComments: boolean = false): ITheme { + if (depComments === true) { + _theme = createTheme({}, depComments); + } return _theme; } @@ -69,9 +73,11 @@ export function removeOnThemeChangeCallback(callback: (theme: ITheme) => void): /** * Applies the theme, while filling in missing slots. + * @param {object} theme - Partial theme object. + * @param {boolean} depComments - Whether to include deprecated tags as comments for deprecated slots. */ -export function loadTheme(theme: IPartialTheme): ITheme { - _theme = createTheme(theme); +export function loadTheme(theme: IPartialTheme, depComments: boolean = false): ITheme { + _theme = createTheme(theme, depComments); // Invoke the legacy method of theming the page as well. legacyLoadTheme({ ..._theme.palette, ..._theme.semanticColors }); @@ -91,8 +97,10 @@ export function loadTheme(theme: IPartialTheme): ITheme { /** * Creates a custom theme definition which can be used with the Customizer. + * @param {object} theme - Partial theme object. + * @param {boolean} depComments - Whether to include deprecated tags as comments for deprecated slots. */ -export function createTheme(theme: IPartialTheme): ITheme { +export function createTheme(theme: IPartialTheme, depComments: boolean = false): ITheme { let newPalette = { ...DefaultPalette, ...theme.palette }; if (!theme.palette || !theme.palette.accent) { @@ -100,8 +108,7 @@ export function createTheme(theme: IPartialTheme): ITheme { } // mix in custom overrides with good slots first, since custom overrides might be used in fixing deprecated slots - let newSemanticColors = { ..._makeSemanticColorsFromPalette(newPalette, !!theme.isInverted), ...theme.semanticColors }; - newSemanticColors = { ..._fixDeprecatedSlots(newSemanticColors), ...theme.semanticColors }; + let newSemanticColors = { ..._makeSemanticColorsFromPalette(newPalette, !!theme.isInverted, depComments), ...theme.semanticColors }; return { palette: newPalette, @@ -117,7 +124,7 @@ export function createTheme(theme: IPartialTheme): ITheme { // Generates all the semantic slot colors based on the Fabric palette. // We'll use these as fallbacks for semantic slots that the passed in theme did not define. // This does NOT fix deprecated slots. -function _makeSemanticColorsFromPalette(p: IPalette, isInverted: boolean): ISemanticColors { +function _makeSemanticColorsFromPalette(p: IPalette, isInverted: boolean, depComments: boolean): ISemanticColors { let toReturn: ISemanticColors = { bodyBackground: p.white, bodyText: p.neutralPrimary, @@ -175,14 +182,23 @@ function _makeSemanticColorsFromPalette(p: IPalette, isInverted: boolean): ISema linkHovered: p.themeDarker, // Deprecated slots, fixed by _fixDeprecatedSlots() + /** + * Deprecated. Use `listText` instead. + * @deprecated + */ listTextColor: '' }; - return toReturn; + return _fixDeprecatedSlots(toReturn, depComments!); } -function _fixDeprecatedSlots(s: ISemanticColors): ISemanticColors { - s.listTextColor = s.listText; +function _fixDeprecatedSlots(s: ISemanticColors, depComments: boolean): ISemanticColors { + // Add @deprecated tag as comment if enabled + let dep = ''; + if (depComments === true) { + dep = ' /* @deprecated */'; + } + s.listTextColor = s.listText + dep; return s; -} \ No newline at end of file +}