Wrapper library for [`office-ui-fabric-react`](https://github.com/OfficeDev/office-ui-fabric-react), exposed as `@angular-react/fabric` and actively maintained and [published on npm](https://www.npmjs.com/package/@angular-react/fabric).

Contains quite a good coverage as far as wrapping the React components go, and for the wrapped components allows passing in all props as `Input`s, listening to all events via `Output`s, as well as pass in render props where applicable (see more details in [ReactWrapperComponent](./Wrapper-libraries:-ReactWrapperComponent.md#Render-props)).

In addition, some components have alternative declarative syntax for things that would make more sense as such in Angular-world, like `<fab-command-bar>` allowing using it's items in a declarative manner, via `<fab-command-bar-item>`. These make authoring apps much simpler in a lot of cases, leveraging Angular's data-binding to it's full extend, instead of changing things imperatively. These should be added when it makes sense and makes using the wrapper components easier, though it does introduce more complexity. More details for these components can be found in the [Declarative Syntax Components](#declarative-syntax-components) section.

## Docs & Guidelines

- We try to stick to the official [`office-ui-fabric-react`](https://developer.microsoft.com/en-us/fabric/#/components) naming whenever possible, with a few minor changes to fit the Angular conventions:
	- Any React component (PascalCase-d) is changed to kebab-case, and prefixed with `fab-`. e.g. `MessageBar` -> `fab-message-bar`, `Checkbox` -> `fab-checkbox`.
	- For any documentation needs - check out the official ones for the React component, and convert the naming according to the above, as needed. Render props are "translated" [as described here](https://github.com/Microsoft/angular-react/wiki/Wrapper-libraries%3A-ReactWrapperComponent#render-props).

- When `office-ui-fabric-react` marks a prop as deprecated, we remove it the next time around we upgrade our dependency on it. We're more harsh with deprecation since the wrapper components are currently authored & maintained completely manually (see [#91](https://github.com/Microsoft/angular-react/issues/91)), and maintaining more props means more manual work.

## Available Components

The following are Fabric components that are readily available to be used. For the most up-to-date version of this list or more details for a specific component, refer to the [components folder][ar-components].

| Component         | Notes                                                                                               | Docs                                      |
| ----------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| breadcrumb        |                                                                                                     | [Breadcrumb][fab-breadcrumb]              |
| button            | Different [button types][ar-button]<br>Supports [contextual-menu-item](#contextual-menu-item)       | [Button][fab-button]                      |
| calendar          | Supports [fab-calendar-strings](#fab-calendar-strings)                                              | [Calendar][fab-calendar]                  |
| callout           | Different [callout types][ar-callout]                                                               | [Callout][fab-callout]                    |
| checkbox          |                                                                                                     | [Checkbox][fab-checkbox]                  |
| choice-group      |                                                                                                     | [ChoiceGroup][fab-choice-group]           |
| combo-box         | Different [combo-box types][ar-combo-box]<br>Supports [fab-combo-box-option](#fab-combo-box-option) | [ComboBox][fab-combo-box]                 |
| command-bar       | Supports [fab-command-bar-item](#fab-command-bar-item)                                              | [CommandBar][fab-command-bar]             |
| contextual-menu   | See [contextual-menu-item](#contextual-menu-item)                                                   | [ContextualMenu][fab-contextual-menu]     |
| date-picker       |                                                                                                     | [DatePicker][fab-date-picker]             |
| details-list      | Supports [fab-details-list-column](#fab-details-list-column) and [fab-group-item](#fab-group-item)  | [DetailsList][fab-details-list]           |
| dialog            | fab-dialog-content and fab-dialog-footer are also supported                                         | [Dialog][fab-dialog]                      |
| divider           |                                                                                                     | N/A                                       |
| dropdown          | Supports [fab-dropdown-option](#fab-dropdown-option)                                                | [Dropdown][fab-dropdown]                  |
| grouped-list      |                                                                                                     | [GroupedList][fab-grouped-list]           |
| hover-card        | Different [hover-card types][ar-hover-card]                                                         | [HoverCard][fab-hover-card]               |
| icon              |                                                                                                     | [Icon][fab-icon]                          |
| image             |                                                                                                     | [Image][fab-image]                        |
| link              |                                                                                                     | [Link][fab-link]                          |
| marquee-selection |                                                                                                     | [MarqueeSelection][fab-marquee-selection] |
| message-bar       | Must bind `[dismissible]="true"` for `(onDismiss)` to work                                          | [MessageBar][fab-message-bar]             |
| modal             |                                                                                                     | [Modal][fab-modal]                        |
| nav               |                                                                                                     | [Nav][fab-nav]                            |
| panel             |                                                                                                     | [Panel][fab-panel]                        |
| persona           | fab-persona-coin is also supported                                                                  | [Persona][fab-persona]                    |
| pickers           | Currently only fab-tag-picker is supported                                                          | [Pickers][fab-pickers]                    |
| pivot             | fab-pivot-item is also supported                                                                    | [Pivot][fab-pivot]                        |
| search-box        |                                                                                                     | [SearchBox][fab-search-box]               |
| shimmer           | fab-shimmer-elements-group is also supported                                                        | [Shimmer][fab-shimmer]                    |
| slider            |                                                                                                     | [Slider][fab-slider]                      |
| spin-button       |                                                                                                     | [SpinButton][fab-spin-button]             |
| spinner           |                                                                                                     | [Spinner][fab-spinner]                    |
| text-field        | Different [text-field types][ar-text-field]                                                         | [TextField][fab-text-field]               |
| toggle            |                                                                                                     | [Toggle][fab-toggle]                      |
| tooltip           | Applies to child element of fab-tooltip-host                                                        | [Tooltip][fab-tooltip]                    |

## Notes and Tips

### click vs. onClick

Angular's default click binding is `(click)` while the Fabric components follow React's `(onClick)`. For safety, it is typically advised to stick with the `(onClick)` binding. Although both bindings will "work", there will be different behaviors in certain circumstances.

For example, in the following code, the click event will still fire even though the button is disabled. This is because the `(click)` binding is attached to the Angular wrapper around the React component.

```html
<fab-default-button [disabled]="true" (click)="doSomething()">
  This will still fire an event!
</fab-default-button>
```

The correct way would be to use `(onClick)` as that event is what gets fired by the actual React button itself:

```html
<fab-default-button [disabled]="true" (onClick)="doSomething()">
  This will not fire an event
</fab-default-button>
```

<a name="declarative-syntax-components"></a>
## Declarative Syntax Components

Fabric components often have input members that expect an object, such as the `columns` member of DetailsList. Although objects can be passed through Angular input bindings, this may be inconvenient if you want to avoid declaring extra objects or have other requirements such as i18n.

The following components and directives have been added to simplify this process for a couple of common scenarios. If what you're looking for is not in the following list, you will need to create a wrapper component in your project to handle passing in different properties of a certain input object. Alternatively, consider contributing to this project to get it added :)

<a name="contextual-menu-item"></a>
### contextual-menu-item ([FabContextualMenuModule][ar-contextual-menu])

Declarative syntax for [IContextualMenuItem](https://github.com/OfficeDev/office-ui-fabric-react/tree/master/packages/office-ui-fabric-react/src/components/ContextualMenu) interface.
Currently supported by different flavors of `fab-*-button` and `fab-command-bar-item`.
Supports additional nesting of `contextual-menu-item`.
Usage example:

```html
<fab-default-button text="Button">
  <contextual-menu-item key="item-1" text="Item 1"></contextual-menu-item>
  <contextual-menu-item key="item-2" text="Item 2">
    <contextual-menu-item key="item-2-1" text="Item 2.1"></contextual-menu-item>
    <contextual-menu-item key="item-2-2" text="Item 2.2"></contextual-menu-item>
  </contextual-menu-item>
  <contextual-menu-item key="item-3" text="Item 3"></contextual-menu-item>
</fab-default-button>
```

<a name="fab-calendar-strings"></a>
### fab-calendar-strings ([FabCalendarModule][ar-calendar])

Declarative syntax for [ICalendarStrings](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/Calendar/Calendar.types.ts) interface.
Currently only supported by `fab-calendar`.
Usage example:

```html
<fab-calendar>
  <fab-calendar-strings
    [months]="['January', 'Fabruary', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']"
    [shortMonths]="['Jan', 'Fab', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']"
    [days]="['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']"
    [shortDays]="['S', 'M', 'T', 'W', 'T', 'F', 'S']"
    goToToday="Go to today"
    weekNumberFormatString="Week number {0}"
  ></fab-calendar-strings>
</fab-calendar>
```

<a name="fab-combo-box-option"></a>
### fab-combo-box-option ([FabComboBoxModule][ar-combo-box])

Declarative syntax for [IComboBoxOption](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/ComboBox/ComboBox.types.ts) interface.
Currently only supported by `fab-combo-box`.
Usage example:  
<sub>Note that the `key` input is actually `optionKey` here.</sub>

```html
<fab-combo-box placeholder="ComboBox">
  <options>
    <fab-combo-box-option optionKey="option-1" text="Option 1">
    <fab-combo-box-option optionKey="option-2" text="Option 2">
    <fab-combo-box-option optionKey="option-3" text="Option 3">
  </options>
</fab-combo-box>
```

<a name="fab-command-bar-item"></a>
### fab-command-bar-item ([FabCommandBarModule][ar-command-bar])

Declarative syntax for [ICommandBarItemProps](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/CommandBar/CommandBar.types.ts) interface.
Currently only supported by `fab-command-bar`.
Supports additional nesting of `contextual-menu-item` and custom renderer via `render` (same parameters as IContextualMenuItem's `onRender`).
Usage example:

```html
<fab-command-bar>
  <items>
    <fab-command-bar-item key="item-1" text="Item 1"></fab-command-bar-item>
    <fab-command-bar-item key="item-2" text="Item 2">
      <contextual-menu-item key="item-2-1" text="Item 2.1"></contextual-menu-item>
      <contextual-menu-item key="item-2-2" text="Item 2.2"></contextual-menu-item>
    </fab-command-bar-item>
  </items>
  <far-items>
    <fab-command-bar-item key="fitem-1" text="F. Item 1"></fab-command-bar-item>
    <fab-command-bar-item key="fitem-2" text="F. Item 2">
      <render>
        <ng-template let-item="item">
          Custom item content
        </ng-template>
      </render>
    </fab-command-bar-item>
  </far-items>
  <overflow-items>
    <fab-command-bar-item key="oitem-1" text="O. Item 1"></fab-command-bar-item>
    <fab-command-bar-item key="oitem-2" text="O. Item 2"></fab-command-bar-item>
  </overflow-items>
</fab-command-bar>
```

<a name="fab-details-list-column"></a>
### fab-details-list-column ([FabDetailsListModule][ar-details-list])

Declarative syntax for [IColumn](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/DetailsList/DetailsList.types.ts) interface.
Currently only supported by `fab-details-list`.
Supports custom renderer via `render` (same parameters as IColumn's `onRender`).
Usage example:

```html
<fab-details-list [items]="shapes">
  <columns>
    <fab-details-list-column key="column-1" name="Column 1" fieldName="name"></fab-details-list-column>
    <fab-details-list-column key="column-2" name="Column 2">
      <render>
        <ng-template let-item="item" let-index="index" let-column="column">
          Size: {{ item.size }}, Index: {{ index }}, Column: {{ column.name }}
        </ng-template>
      </render>
    </fab-details-list-column>
    <fab-details-list-column key="column-3" name="Column 3" fieldName="color"></fab-details-list-column>
  </columns>
</fab-details-list>
```

<a name="fab-dropdown-option"></a>
### fab-dropdown-option ([FabDropdownModule][ar-dropdown])

Declarative syntax for [IDropdownOption](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/Dropdown/Dropdown.types.ts) interface.
Currently only supported by `fab-dropdown`.
Usage example:  
<sub>Note that the `key` input is actually `optionKey` here.</sub>

```html
<fab-dropdown placeholder="Dropdown">
  <options>
    <fab-dropdown-option optionKey="option-1" text="Option 1">
    <fab-dropdown-option optionKey="option-2" text="Option 2">
    <fab-dropdown-option optionKey="option-3" text="Option 3">
  </options>
</fab-dropdown>
```

<a name="fab-group-item"></a>
### fab-group-item ([FabGroupModule][ar-group])

Declarative syntax for [IGroup](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/GroupedList/GroupedList.types.ts) interface.
Currently only supported by `fab-details-list`.
Supports additional nesting of `fab-group-item`.
Usage example:

```html
<fab-details-list [items]="items">
  <groups>
    <fab-group-item key="group-1" name="Group 1" [count]="3" [startIndex]="0"></fab-group-item>
    <fab-group-item key="group-2" name="Group 2" [count]="3" [startIndex]="3">
      <fab-group-item key="group-2-1" name="Group 2.1" [count]="2" [startIndex]="3"></fab-group-item>
      <fab-group-item key="group-2-2" name="Group 2.2" [count]="1" [startIndex]="5"></fab-group-item>
    </fab-group-item>
    <fab-group-item key="group-3" name="Group 3" [count]="10" [startIndex]="6"></fab-group-item>
  </groups>
</fab-details-list>
```

[ar-components]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components
[ar-button]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/button
[ar-calendar]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/calendar
[ar-callout]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/callout
[ar-combo-box]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/combo-box
[ar-command-bar]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/command-bar
[ar-contextual-menu]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/contextual-menu
[ar-details-list]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/details-list
[ar-dropdown]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/dropdown
[ar-group]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/group
[ar-hover-card]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/hover-card
[ar-text-field]: https://github.com/Microsoft/angular-react/tree/master/libs/fabric/src/lib/components/text-field
[fab-home]: https://developer.microsoft.com/en-us/fabric
[fab-components]: https://developer.microsoft.com/en-us/fabric#/components
[fab-breadcrumb]: https://developer.microsoft.com/en-us/fabric#/components/breadcrumb
[fab-button]: https://developer.microsoft.com/en-us/fabric#/components/button
[fab-calendar]: https://developer.microsoft.com/en-us/fabric#/components/calendar
[fab-callout]: https://developer.microsoft.com/en-us/fabric#/components/callout
[fab-checkbox]: https://developer.microsoft.com/en-us/fabric#/components/checkbox
[fab-choice-group]: https://developer.microsoft.com/en-us/fabric#/components/choicegroup
[fab-combo-box]: https://developer.microsoft.com/en-us/fabric#/components/combobox
[fab-command-bar]: https://developer.microsoft.com/en-us/fabric#/components/commandbar
[fab-contextual-menu]: https://developer.microsoft.com/en-us/fabric#/components/contextualmenu
[fab-date-picker]: https://developer.microsoft.com/en-us/fabric#/components/datepicker
[fab-details-list]: https://developer.microsoft.com/en-us/fabric#/components/detailslist
[fab-dialog]: https://developer.microsoft.com/en-us/fabric#/components/dialog
[fab-dropdown]: https://developer.microsoft.com/en-us/fabric#/components/dropdown
[fab-grouped-list]: https://developer.microsoft.com/en-us/fabric#/components/groupedlist
[fab-hover-card]: https://developer.microsoft.com/en-us/fabric#/components/hovercard
[fab-icon]: https://developer.microsoft.com/en-us/fabric#/components/icon
[fab-image]: https://developer.microsoft.com/en-us/fabric#/components/image
[fab-link]: https://developer.microsoft.com/en-us/fabric#/components/link
[fab-marquee-selection]: https://developer.microsoft.com/en-us/fabric#/components/marqueeselection
[fab-message-bar]: https://developer.microsoft.com/en-us/fabric#/components/messagebar
[fab-modal]: https://developer.microsoft.com/en-us/fabric#/components/modal
[fab-nav]: https://developer.microsoft.com/en-us/fabric#/components/nav
[fab-panel]: https://developer.microsoft.com/en-us/fabric#/components/panel
[fab-persona]: https://developer.microsoft.com/en-us/fabric#/components/persona
[fab-pickers]: https://developer.microsoft.com/en-us/fabric#/components/pickers
[fab-pivot]: https://developer.microsoft.com/en-us/fabric#/components/pivot
[fab-search-box]: https://developer.microsoft.com/en-us/fabric#/components/searchbox
[fab-shimmer]: https://developer.microsoft.com/en-us/fabric#/components/shimmer
[fab-slider]: https://developer.microsoft.com/en-us/fabric#/components/slider
[fab-spin-button]: https://developer.microsoft.com/en-us/fabric#/components/spinbutton
[fab-spinner]: https://developer.microsoft.com/en-us/fabric#/components/spinner
[fab-text-field]: https://developer.microsoft.com/en-us/fabric#/components/textfield
[fab-toggle]: https://developer.microsoft.com/en-us/fabric#/components/toggle
[fab-tooltip]: https://developer.microsoft.com/en-us/fabric#/components/tooltip