Persona: Deprecate primaryText

.vscode/tasks.json

@@ -17,6 +17,23 @@
         "kind": "build",
         "isDefault": true
       }
+    },
+    {
+      "label": "Typescript (vr-tests) watch",
+      "type": "process",
+      "command": "node",
+      "args": [
+        "./scripts/node_modules/typescript/bin/tsc",
+        "-p",
+        "apps/vr-tests/tsconfig.json",
+        "-w",
+        "--noEmit"
+      ],
+      "problemMatcher": "$tsc",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
     }
   ]
 }

apps/vr-tests/src/stories/PeoplePicker.stories.tsx

@@ -12,7 +12,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 1,
     imageUrl: TestImages.personaFemale,
     imageInitials: 'PV',
-    primaryText: 'Annie Lindqvist',
+    text: 'Annie Lindqvist',
     secondaryText: 'Designer',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -22,7 +22,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 2,
     imageUrl: TestImages.personaMale,
     imageInitials: 'AR',
-    primaryText: 'Aaron Reid',
+    text: 'Aaron Reid',
     secondaryText: 'Designer',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -32,7 +32,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 3,
     imageUrl: TestImages.personaMale,
     imageInitials: 'AL',
-    primaryText: 'Alex Lundberg',
+    text: 'Alex Lundberg',
     secondaryText: 'Software Developer',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -42,7 +42,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 4,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Roko Kolar',
+    text: 'Roko Kolar',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -52,7 +52,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 5,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Alex Lundberg1',
+    text: 'Alex Lundberg1',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -62,7 +62,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 6,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Alex Lundberg2',
+    text: 'Alex Lundberg2',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -72,7 +72,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 7,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Alex Lundberg2',
+    text: 'Alex Lundberg2',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -82,7 +82,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 8,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Alex Lundberg3',
+    text: 'Alex Lundberg3',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -92,7 +92,7 @@ const people: (IPersonaProps & { key: string | number })[] = [
     key: 9,
     imageUrl: TestImages.personaMale,
     imageInitials: 'RK',
-    primaryText: 'Alex Lundberg4',
+    text: 'Alex Lundberg4',
     secondaryText: 'Financial Analyst',
     tertiaryText: 'In a meeting',
     optionalText: 'Available at 4:00pm',
@@ -110,7 +110,7 @@ const suggestionProps = {
   suggestionsContainerAriaLabel: 'Suggested contacts'
 };
 
-const getTextFromItem = (persona: IPersonaProps): string => persona.primaryText as string;
+const getTextFromItem = (persona: IPersonaProps): string => persona.text as string;
 
 const getPeople = () => people;
 

apps/vr-tests/src/stories/Persona.stories.tsx

@@ -3,13 +3,13 @@ import * as React from 'react';
 import Screener, { Steps } from 'screener-storybook/src/screener';
 import { storiesOf } from '@storybook/react';
 import { FabricDecorator } from '../utilities';
-import { Persona, PersonaPresence, PersonaSize } from 'office-ui-fabric-react';
+import { IPersonaProps, Persona, PersonaPresence, PersonaSize } from 'office-ui-fabric-react';
 import { TestImages } from '../common/TestImages';
 
-const examplePersona = {
+const examplePersona: IPersonaProps = {
   imageUrl: TestImages.personaFemale,
   imageInitials: 'AL',
-  primaryText: 'Annie Lindqvist',
+  text: 'Annie Lindqvist',
   secondaryText: 'Software Engineer',
   tertiaryText: 'In a meeting',
   optionalText: 'Available at 4:00pm'
@@ -104,37 +104,37 @@ storiesOf('Persona', module)
     <div>
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.away'
+        text='PersonaPresence.away'
         presence={ PersonaPresence.away }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.blocked'
+        text='PersonaPresence.blocked'
         presence={ PersonaPresence.blocked }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.busy'
+        text='PersonaPresence.busy'
         presence={ PersonaPresence.busy }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.dnd'
+        text='PersonaPresence.dnd'
         presence={ PersonaPresence.dnd }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.none'
+        text='PersonaPresence.none'
         presence={ PersonaPresence.none }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.offline'
+        text='PersonaPresence.offline'
         presence={ PersonaPresence.offline }
       />
       <Persona
         { ...examplePersona }
-        primaryText='PersonaPresence.online'
+        text='PersonaPresence.online'
         presence={ PersonaPresence.online }
       />
     </div>

common/changes/office-ui-fabric-react/jagore-deprecate-persona-primaryText_2018-05-08-17-37.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Deprecate Persona's primaryText prop and add replacement text prop.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "[email protected]"
+}

ghdocs/BestPractices/Deprecation.md

@@ -0,0 +1,60 @@
+# Deprecation Guidelines
+
+This guide outlines recommendations for deprecating API behavior, particularly related to component props.
+
+An example PR following these steps can be found here:
+**https://github.com/OfficeDev/office-ui-fabric-react/pull/4811**
+
+## Deprecation Steps
+1. Ensure snapshot tests exist covering existing props functionality as a reference check against deprecation changes.
+    - The props you're deprecating should have representation in the snapshot output. Sometimes this may require getting the component under test into a certain state.
+1. Keep the tests using deprecated props named in a file with deprecated suffix, such as `Persona.test.tsx` -> `Persona.deprecated.test.tsx`.
+1. Copy the test's snapshot output (or ensure it's the same if regenerated.)
+1. Modify existing tests to use new prop.
+    - Snapshot output should be identical in most cases, particularly if props naming is the only thing changing.
+1. Add new property to interface.
+1. Optionally, temporarily comment out old prop to help find all uses throughout code base and change. Take care that as of writing some uses are not covered by TypeScript as part of build, such as some objects created in tests without type declaration and Screener tests in `apps/vr-tests`.
+    - If you use VS Code, there is a task available to help aid called `Typescript (vr-tests) watch` which you can run via `Tasks -> Run Task`. You may have to rebuild occasionally to get the types reflected across packages correctly.
+1. Update components that consume property as needed to support both deprecated and new props.
+    - Be sure to consider other components that both use and extend the modified interface. If a component needed a change, there's a good chance it will also need to continue supporting the deprecated prop and should also have deprected tests.
+1. Move deprecated prop to end of interface, update comments with deprecation description and add @deprecated.
+
+    ```tsx
+    /**
+    * Primary text to display, usually the name of the person.
+    * @deprecated Use 'text' instead.
+    */
+    primaryText?: string;
+    ```
+
+1. Make sure old and new tests pass.
+1. Add call to warnDeprecations in constructor, like:
+
+    ```tsx
+    constructor(props: IPersonaCoinProps) {
+      super(props);
+
+      // 'primaryText' is deprecated and 'text' should be used instead
+      this._warnDeprecations({ 'primaryText': 'text' });
+    }
+    ```
+1. warnDeprecations will most likely cause deprecated tests to fail, requiring mocking of warnDeprecations. Please make note to clear mock at end of tests as shown below.
+
+    ```tsx
+    import * as WarnUtil from '@uifabric/utilities/lib/warn';
+
+    describe('MyTests', () => {
+      beforeAll(() => {
+        // Prevent warn deprecations from failing test
+        jest.spyOn(WarnUtil, 'warnDeprecations').mockImplementation(() => { /** no impl **/ });
+      });
+
+      afterAll(() => {
+        jest.restoreAllMocks();
+      });
+
+      // tests ...
+    });
+    ```
+
+

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

@@ -4,6 +4,7 @@ import * as renderer from 'react-test-renderer';
 import { ActivityItem } from './ActivityItem';
 import { Icon } from '../../Icon';
 import { TestImages } from '../../common/TestImages';
+import { IPersonaSharedProps } from '../Persona';
 
 const defaultProps = {
   key: 1,
@@ -12,17 +13,17 @@ const defaultProps = {
   timeStamp: 'timestamp text'
 };
 
-const defaultPersonaProps = [
+const defaultPersonaProps: IPersonaSharedProps[] = [
   {
     imageInitials: 'TN',
-    primaryText: 'Test Name'
+    text: 'Test Name'
   },
   {
     imageUrl: TestImages.personaFemale
   },
   {
     imageInitials: 'AN',
-    primaryText: 'Another Name'
+    text: 'Another Name'
   },
   {
     imageUrl: TestImages.personaMale

packages/office-ui-fabric-react/src/components/ActivityItem/examples/ActivityItem.Compact.Example.tsx

@@ -39,14 +39,14 @@ export class ActivityItemCompactExample extends React.Component<React.Props<Acti
         activityPersonas: [
           {
             imageInitials: 'PT',
-            primaryText: 'Robert Larsson'
+            text: 'Robert Larsson'
           },
           {
             imageUrl: TestImages.personaMale
           },
           {
             imageInitials: 'EC',
-            primaryText: 'Eduarda Costa'
+            text: 'Eduarda Costa'
           }
         ],
         isCompact: true

packages/office-ui-fabric-react/src/components/ActivityItem/examples/ActivityItem.Persona.Example.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { css, classNamesFunction } from '../../../Utilities';
-import { ActivityItem } from '../ActivityItem';
+import { ActivityItem, IActivityItemProps } from '..';
 import {
   getStyles,
   IActivityItemExampleStyleProps,
@@ -15,7 +15,7 @@ export class ActivityItemPersonaExample extends React.Component<React.Props<Acti
     const classNames = getClassNames(getStyles);
 
     // tslint:disable:jsx-no-lambda
-    const activityItemExamples = [
+    const activityItemExamples: (IActivityItemProps & { key: string | number })[] = [
       {
         key: 1,
         activityDescription: [
@@ -43,7 +43,7 @@ export class ActivityItemPersonaExample extends React.Component<React.Props<Acti
         activityPersonas: [
           {
             imageInitials: 'JM',
-            primaryText: 'Javiera Márquez'
+            text: 'Javiera Márquez'
           },
           {
             imageUrl: TestImages.personaFemale
@@ -62,7 +62,7 @@ export class ActivityItemPersonaExample extends React.Component<React.Props<Acti
         activityPersonas: [
           {
             imageInitials: 'RL',
-            primaryText: 'Robert Larsson'
+            text: 'Robert Larsson'
           },
           {
             imageUrl: TestImages.personaMale
@@ -84,14 +84,14 @@ export class ActivityItemPersonaExample extends React.Component<React.Props<Acti
         activityPersonas: [
           {
             imageInitials: 'JC',
-            primaryText: 'Jin Cheng'
+            text: 'Jin Cheng'
           },
           {
             imageUrl: TestImages.personaMale
           },
           {
             imageInitials: 'AL',
-            primaryText: 'Annie Lindqvist'
+            text: 'Annie Lindqvist'
           },
           {
             imageUrl: TestImages.personaFemale

packages/office-ui-fabric-react/src/components/Checkbox/examples/Checkbox.ImplementationExamples.tsx

@@ -101,6 +101,6 @@ export class CheckboxImplementationExamples extends React.Component<{}, ICheckbo
 
   private _renderPersonaLabel(props: ICheckboxProps): JSX.Element {
     const DEFAULT_IMAGE_URL = '/_layouts/15/userphoto.aspx?size=S&accountname=';
-    return <Persona primaryText={ props.label } imageUrl={ DEFAULT_IMAGE_URL } size={ PersonaSize.size32 } />;
+    return <Persona text={ props.label } imageUrl={ DEFAULT_IMAGE_URL } size={ PersonaSize.size32 } />;
   }
 }

packages/office-ui-fabric-react/src/components/DocumentCard/DocumentCardActivity.tsx

@@ -44,7 +44,7 @@ export class DocumentCardActivity extends BaseComponent<IDocumentCardActivityPro
       <div className={ css('ms-DocumentCardActivity-avatar', styles.avatar) }>
         <PersonaCoin
           imageInitials={ person.initials }
-          primaryText={ person.name }
+          text={ person.name }
           imageUrl={ person.profileImageSrc }
           initialsColor={ person.initialsColor }
           allowPhoneInitials={ person.allowPhoneInitials }