@fluentui-react-native/experimental-avatar 0.14.26 → 0.14.27

package/src/__tests__/JSAvatar.test.jsx

@@ -0,0 +1,156 @@
+import * as React from 'react';
+import { JSAvatar } from '..';
+import { getInitials, validateAlphabeticalCharacters, removeTitlesFromName } from '../useAvatar';
+import * as renderer from 'react-test-renderer';
+
+const alphabeticalTestNames = [
+  'Marie',
+  'Aadi KaPoor',
+  'Marie Beaudouin',
+  'Aadi Meni KaPoor',
+  'Aadi Meni Ka Jr',
+  'Will Little (Teams)',
+  'Will Little-Tanaka',
+  '-Aadi Kapoor',
+  'Richard 23 Feynman',
+  '* Richard *',
+  'Richard Feynman [Teams]',
+  'Richard Feynman {Teams}',
+];
+const alphabeticalInitials = ['M', 'AK', 'MB', 'AK', 'AK', 'WL', 'WL', 'AK', 'RF', 'R', 'RF', 'RF'];
+const otherTestNames = ['(206) 123-4567', '耿盈盈']; // will return this case after bug bash - '耿 James'
+const namesWithTitles = ['Mr Feynman', 'Dr Richard Feynman'];
+const initialsForNameWithTitles = ['F', 'RF'];
+
+it('renders Avatar', () => {
+  const tree = renderer.create(<JSAvatar />).toJSON();
+  expect(tree).toMatchSnapshot();
+});
+
+describe('validateAlphabeticalCharacters method', () => {
+  it('validates alphabetical characters', () => {
+    for (let i = 0; i < alphabeticalTestNames.length; i++) {
+      expect(validateAlphabeticalCharacters(alphabeticalTestNames[i])).toBeTruthy();
+    }
+    for (let i = 0; i < otherTestNames.length; i++) {
+      expect(validateAlphabeticalCharacters(otherTestNames[i])).toBeFalsy();
+    }
+  });
+
+  it("doesn't validate undefined name", () => {
+    expect(validateAlphabeticalCharacters(undefined)).toBeFalsy();
+  });
+  it("doesn't validate an empty string", () => {
+    expect(validateAlphabeticalCharacters('')).toBeFalsy();
+  });
+  it("doesn't validate null name", () => {
+    expect(validateAlphabeticalCharacters(null)).toBeFalsy();
+  });
+});
+
+describe('removeTitlesFromName method', () => {
+  it('removes titles from the name', () => {
+    const words = ['Mr', 'Faynman'];
+    expect(removeTitlesFromName(words)).toStrictEqual(['Faynman']);
+  });
+  // it('removes multiword titles from the name', () => {
+  //   const name = 'Consul General Richard Faynman';
+  //   expect(removeTitlesFromName(name)).toStrictEqual(['Richard Faynman']);
+  // });
+});
+
+describe('getInitials method', () => {
+  it('returns correct initials', () => {
+    const test = getInitials('-Test   str  with *spaces');
+    expect(test).toBe('TS');
+  });
+
+  it('returns an empty string if name is undefined', () => {
+    expect(getInitials(undefined)).toBe('');
+  });
+
+  it('return initials for alphabetical words', () => {
+    for (let i = 0; i < alphabeticalTestNames.length; i++) {
+      expect(getInitials(alphabeticalTestNames[i])).toBe(alphabeticalInitials[i]);
+    }
+  });
+
+  it('return initials for words with titles', () => {
+    for (let i = 0; i < namesWithTitles.length; i++) {
+      expect(getInitials(namesWithTitles[i])).toBe(initialsForNameWithTitles[i]);
+    }
+  });
+
+  it("returns initials when there's a coma", () => {
+    expect(getInitials('Second, First')).toEqual('SF');
+  });
+
+  // Unit tests from Web
+  it('handles null inputs', () => {
+    expect(getInitials(null)).toEqual('');
+    expect(getInitials(undefined)).toEqual('');
+  });
+
+  // it('calculates an expected initials in LTR for non-ASCII characters', () => {
+  //   expect(getInitials('Írissa Þórðardóttir')).toEqual('ÍÞ');
+  //   expect(getInitials('Øyvind Åsen')).toEqual('ØÅ');
+  // });
+
+  it('calculates an expected initials in LTR with a hypen', () => {
+    expect(getInitials('David Zearing-Goff')).toEqual('DZ');
+  });
+
+  // it('calculates an expected initials in LTR with numbers', () => {
+  //   expect(getInitials('4lex 5loo')).toEqual('45');
+  // });
+  it('calculates an expected initials in LTR with multiple parentheses, extra spaces, and unwanted characters', () => {
+    const result = getInitials(' !@#$%^&*()=+ (Alpha) David   (The man) `~<>,./?[]{}|   Goff   (Gamma)    ');
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in LTR with multiple types of unwanted text', () => {
+    const result = getInitials(' !@#$%^&*()=+ (Alpha) David   (The man) `~<>,./?[]{}|   Goff   (Gamma)  [Beta]  ');
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials for Arabic names', () => {
+    expect(getInitials('خسرو رحیمی')).toEqual('');
+  });
+
+  it('calculates an expected initials for Chinese names', () => {
+    expect(getInitials('桂英')).toEqual('');
+    expect(getInitials('佳')).toEqual('');
+    expect(getInitials('宋智洋')).toEqual('');
+  });
+
+  it('calculates an expected initials for Korean names', () => {
+    expect(getInitials('강현')).toEqual('');
+    expect(getInitials('최종래')).toEqual('');
+    expect(getInitials('남궁 성종')).toEqual('');
+  });
+
+  it('calculates an expected initials for Japanese names', () => {
+    expect(getInitials('松田')).toEqual('');
+    expect(getInitials('海野')).toEqual('');
+    expect(getInitials('かり')).toEqual('');
+  });
+
+  // it('validates phone numbers', () => {
+  // expect(getInitials('12345678')).toEqual('');
+  // expect(getInitials('+1 (555) 123-4567 ext.4567')).toEqual('');
+  // expect(getInitials('+47 12 34 56 78 (X 5678)')).toEqual('4');
+  // expect(getInitials('47 12 34')).toEqual('');
+  // expect(getInitials('47 12')).toEqual('');
+  // expect(getInitials('1 Ext 2')).toEqual('');
+  // result = getInitials('James Ext 2');
+  // expect(result).toEqual('JE');
+  // result = getInitials('1x1');
+  // expect(result).toEqual('');
+  // result = getInitials('1y1');
+  // expect(result).toEqual('');
+  // result = getInitials('1');
+  // expect(result).toEqual('');
+  // result = getInitials('A 2');
+  // expect(result).toEqual('A');
+  // });
+});

package/src/__tests__/__snapshots__/JSAvatar.test.jsx.snap

@@ -0,0 +1,34 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`renders Avatar 1`] = `
+<View
+  shape="circular"
+  style={
+    Object {
+      "alignItems": "flex-end",
+      "flexDirection": "row",
+      "height": 24,
+      "horizontalIconAlignment": "end",
+      "justifyContent": "flex-end",
+      "opacity": 1,
+      "verticalIconAlignment": "end",
+      "width": 24,
+    }
+  }
+>
+  <View
+    style={
+      Object {
+        "alignItems": "center",
+        "alignSelf": "stretch",
+        "backgroundColor": "#4f6bed",
+        "borderRadius": 9999,
+        "flexGrow": 1,
+        "height": 24,
+        "justifyContent": "center",
+        "width": 24,
+      }
+    }
+  />
+</View>
+`;

package/src/titles.ts

@@ -0,0 +1,108 @@
+export const titles = new Set<string>([
+  'Mr',
+  'Mrs',
+  'Miss',
+  'Ms',
+  'Dr',
+  'Admiral',
+  'Air Comm',
+  'Ambassador',
+  'Baron',
+  'Baroness',
+  'Brig & Mrs',
+  'Brig Gen',
+  'Brigadier',
+  'Brother',
+  'Canon',
+  'Capt',
+  'Chief',
+  'Cllr',
+  'Col',
+  'Commander',
+  'Commander & Mrs',
+  'Consul',
+  'Consul General',
+  'Count',
+  'Countess',
+  'Countess of',
+  'Cpl',
+  'Dame',
+  'Deputy',
+  'Dr & Mrs',
+  'Drs',
+  'Duchess',
+  'Duke',
+  'Earl',
+  'Father',
+  'General',
+  'Gräfin',
+  'HE',
+  'HMA',
+  'Her Grace',
+  'His Excellency',
+  'Jr',
+  'Judge',
+  'Justice',
+  'Lady',
+  'Lic',
+  'Llc',
+  'Lord',
+  'Lord & Lady',
+  'Lt',
+  'Lt Col',
+  'Lt Cpl',
+  'M',
+  'Madam',
+  'Madame',
+  'Major',
+  'Major General',
+  'Marchioness',
+  'Marquis',
+  'Minister',
+  'Mme',
+  'Mr & Dr',
+  'Mr & Mrs',
+  'Mr & Ms',
+  'Prince',
+  'Princess',
+  'Professor',
+  'Prof',
+  'Prof & Dr',
+  'Prof & Mrs',
+  'Prof & Rev',
+  'Prof Dame',
+  'Prof Dr',
+  'Pvt',
+  'Rabbi',
+  'Rear Admiral',
+  'Rev',
+  'Rev & Mrs',
+  'Rev Canon',
+  'Rev Dr',
+  'Senator',
+  'Sgt',
+  'Sheriff',
+  'Sir',
+  'Sir & Lady',
+  'Sister',
+  'Sr',
+  'Sqr. Leader',
+  'The Earl of',
+  'The Hon',
+  'The Hon Dr',
+  'The Hon Lady',
+  'The Hon Lord',
+  'The Hon Mrs',
+  'The Hon Sir',
+  'The Honourable',
+  'The Rt Hon',
+  'The Rt Hon Dr',
+  'The Rt Hon Lord',
+  'The Rt Hon Sir',
+  'The Rt Hon Visc',
+  'Viscount',
+  'van',
+  'I',
+  'II',
+  'III',
+]);

package/src/useAvatar.ts

@@ -1,6 +1,7 @@
 import { JSAvatarProps, AvatarInfo, JSAvatarState } from './JSAvatar.types';
 import { ImageProps, ImageSourcePropType } from 'react-native';
 import { PresenceBadgeProps } from '@fluentui-react-native/badge';
+import { titles } from './titles';
 /**
  * Re-usable hook for FURN Avatar.
  * This hook configures Avatar props and state for FURN Avatar.
@@ -9,7 +10,7 @@ import { PresenceBadgeProps } from '@fluentui-react-native/badge';
  * @returns configured props and state for FURN Avatar
  */
 export const useAvatar = (props: JSAvatarProps): AvatarInfo => {
-  const { active, accessibilityLabel, activeAppearance, badge, ring, src, shape, ...rest } = props;
+  const { active, accessibilityLabel, activeAppearance, badge, initials, name, src, ring, shape, ...rest } = props;
 
   const showRing = active === 'active' && activeAppearance === 'ring';
   const transparentRing = !!ring?.transparent;
@@ -31,6 +32,8 @@ export const useAvatar = (props: JSAvatarProps): AvatarInfo => {
     showBadge,
   };
 
+  const _initials = initials || getInitials(name);
+
   return {
     props: {
       shape: shape || 'circular',
@@ -39,9 +42,56 @@ export const useAvatar = (props: JSAvatarProps): AvatarInfo => {
       activeAppearance,
       image: imageProps,
       badge: badgeProps,
+      initials: _initials,
     },
     state: {
       ...state,
     },
   };
 };
+
+/**
+ * A function which takes a name and returns initials
+ *
+ * @param name
+ * @returns initials. First letter of the word if only one word was provided.
+ * First letters of the first and last words if more words were provided.
+ * Words in braces, titles, special characters, parantheses and dashes should be ignored.
+ */
+export const getInitials = (name: string): string => {
+  if (!name && !validateAlphabeticalCharacters(name)) {
+    return '';
+  }
+  // prettier-ignore
+  const nonWordRegExp = new RegExp('\\W+(?<!\\S-)', 'g');
+  const wordsInBracesRegExp = new RegExp('(\\(|\\[|\\{)\\w+(\\)|\\]|\\})', 'g');
+  let words = name.replace(wordsInBracesRegExp, ' ').replace(nonWordRegExp, ' ').trim().split(' ');
+  words = removeTitlesFromName(words);
+  const wordsLength = words.length;
+  const lastWordIdx = wordsLength - 1;
+  const initials = `${words[0].charAt(0).toUpperCase()}${wordsLength > 1 ? words[lastWordIdx].charAt(0).toUpperCase() : ''}`;
+  return initials;
+};
+
+/**
+ * A function which verifies whether a name contains non-alphabetical characters
+ *
+ * @param name
+ * @returns true if the name contains alphabetical characters. Returns false if there are
+ * numeric values or the first character is non-alphabetical. In this case avatar should
+ * fall back to icon.
+ */
+export const validateAlphabeticalCharacters = (name: string): boolean => {
+  const alphabeticalRegExp = new RegExp('[a-zA-Z]', 'g');
+  return name ? alphabeticalRegExp.test(name) : false;
+};
+
+/**
+ * A function which verifies whether words array contains title
+ *
+ * @param words array of words in name
+ * @returns array of words without titles
+ */
+export const removeTitlesFromName = (words: string[]): string[] => {
+  return words.filter((word) => !titles.has(word));
+};

package/src/utils/getInitials.test.ts

@@ -0,0 +1,154 @@
+import { getInitials } from './getInitials';
+
+describe('getInitials', () => {
+  it('handles null inputs', () => {
+    let result = getInitials(null, false);
+    expect(result).toEqual('');
+
+    result = getInitials(undefined, false);
+    expect(result).toEqual('');
+  });
+
+  it('calculates an expected initials in LTR', () => {
+    const result = getInitials('Kat Larrson', false);
+    expect(result).toEqual('KL');
+  });
+
+  it('calculates an expected initials in LTR for non-ASCII characters', () => {
+    let result = getInitials('Írissa Þórðardóttir', false);
+    expect(result).toEqual('ÍÞ');
+
+    result = getInitials('Øyvind Åsen', false);
+    expect(result).toEqual('ØÅ');
+  });
+
+  it('calculates an expected initials in LTR with a hypen', () => {
+    const result = getInitials('David Zearing-Goff', false);
+    expect(result).toEqual('DZ');
+  });
+
+  it('calculates an expected initials in LTR with numbers', () => {
+    const result = getInitials('4lex 5loo', false);
+    expect(result).toEqual('45');
+  });
+
+  it('calculates an expected initials in LTR with parentheses', () => {
+    const result = getInitials('David (The man) Goff', false);
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in LTR with brackets', () => {
+    const result = getInitials('David Goff [The man]', false);
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in LTR with curly braces', () => {
+    const result = getInitials('David {The man} Goff', false);
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in LTR with multiple parentheses, extra spaces, and unwanted characters', () => {
+    const result = getInitials(' !@#$%^&*()=+ (Alpha) David   (The man) `~<>,./?[]{}|   Goff   (Gamma)    ', false);
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in LTR with multiple types of unwanted text', () => {
+    const result = getInitials(' !@#$%^&*()=+ (Alpha) David   (The man) `~<>,./?[]{}|   Goff   (Gamma)  [Beta]  ', false);
+    expect(result).toEqual('DG');
+  });
+
+  it('calculates an expected initials in RTL if one was not specified', () => {
+    const result = getInitials('Kat Larrson', true);
+    expect(result).toEqual('LK');
+  });
+
+  it('calculates an expected initials in LTR for names with multiple components', () => {
+    let result = getInitials('A', false);
+    expect(result).toEqual('A');
+
+    result = getInitials('A B', false);
+    expect(result).toEqual('AB');
+
+    result = getInitials('A B C', false);
+    expect(result).toEqual('AC');
+
+    result = getInitials('A B C D', false);
+    expect(result).toEqual('A');
+  });
+
+  it('calculates an expected initials for Arabic names', () => {
+    const result = getInitials('خسرو رحیمی', true);
+    expect(result).toEqual('');
+  });
+
+  it('calculates an expected initials for Chinese names', () => {
+    let result = getInitials('桂英', false);
+    expect(result).toEqual('');
+
+    result = getInitials('佳', false);
+    expect(result).toEqual('');
+
+    result = getInitials('宋智洋', false);
+    expect(result).toEqual('');
+  });
+
+  it('calculates an expected initials for Korean names', () => {
+    let result = getInitials('강현', false);
+    expect(result).toEqual('');
+
+    result = getInitials('최종래', false);
+    expect(result).toEqual('');
+
+    result = getInitials('남궁 성종', false);
+    expect(result).toEqual('');
+  });
+
+  it('calculates an expected initials for Japanese names', () => {
+    let result = getInitials('松田', false);
+    expect(result).toEqual('');
+
+    result = getInitials('海野', false);
+    expect(result).toEqual('');
+
+    result = getInitials('かり', false);
+    expect(result).toEqual('');
+  });
+
+  it('calculates expected initials for phone numbers', () => {
+    let result = getInitials('12345678', false);
+    expect(result).toEqual('');
+
+    result = getInitials('+1 (555) 123-4567 ext.4567', false);
+    expect(result).toEqual('');
+
+    result = getInitials('+47 12 34 56 78 (X 5678)', false);
+    expect(result).toEqual('');
+
+    result = getInitials('+47 12 34 56 78 (X 5678)', false, true);
+    expect(result).toEqual('4');
+
+    result = getInitials('47 12 34', false, true);
+    expect(result).toEqual('43');
+
+    result = getInitials('47 12', false, true);
+    expect(result).toEqual('41');
+
+    result = getInitials('1 Ext 2', false);
+    expect(result).toEqual('');
+
+    result = getInitials('James Ext 2', false);
+    expect(result).toEqual('J2');
+
+    result = getInitials('1x1', false);
+    expect(result).toEqual('');
+
+    result = getInitials('1y1', false);
+    expect(result).toEqual('1');
+
+    result = getInitials('1', false);
+    expect(result).toEqual('1');
+
+    result = getInitials('A 2', false);
+    expect(result).toEqual('A2');
+  });
+});

package/src/utils/getInitials.ts

@@ -0,0 +1,92 @@
+/**
+ * Regular expressions matching characters to ignore when calculating the initials.
+ */
+
+/**
+ * Regular expression matching characters within various types of enclosures, including the enclosures themselves
+ *  so for example, (xyz) [xyz] {xyz} all would be ignored
+ */
+const UNWANTED_ENCLOSURES_REGEX: RegExp = /[\(\[\{][^\)\]\}]*[\)\]\}]/g;
+
+/**
+ * Regular expression matching special ASCII characters except space, plus some unicode special characters.
+ * Applies after unwanted enclosures have been removed
+ */
+const UNWANTED_CHARS_REGEX: RegExp = /[\0-\u001F\!-/:-@\[-`\{-\u00BF\u0250-\u036F\uD800-\uFFFF]/g;
+
+/**
+ * Regular expression matching phone numbers. Applied after chars matching UNWANTED_CHARS_REGEX have been removed
+ * and number has been trimmed for whitespaces
+ */
+const PHONENUMBER_REGEX: RegExp = /^\d+[\d\s]*(:?ext|x|)\s*\d+$/i;
+
+/** Regular expression matching one or more spaces. */
+const MULTIPLE_WHITESPACES_REGEX: RegExp = /\s+/g;
+
+/**
+ * Regular expression matching languages for which we currently don't support initials.
+ * Arabic:   Arabic, Arabic Supplement, Arabic Extended-A.
+ * Korean:   Hangul Jamo, Hangul Compatibility Jamo, Hangul Jamo Extended-A, Hangul Syllables, Hangul Jamo Extended-B.
+ * Japanese: Hiragana, Katakana.
+ * CJK:      CJK Unified Ideographs Extension A, CJK Unified Ideographs, CJK Compatibility Ideographs,
+ *             CJK Unified Ideographs Extension B
+ */
+// eslint-disable-next-line @fluentui/max-len
+const UNSUPPORTED_TEXT_REGEX: RegExp =
+  /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\u1100-\u11FF\u3130-\u318F\uA960-\uA97F\uAC00-\uD7AF\uD7B0-\uD7FF\u3040-\u309F\u30A0-\u30FF\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF]|[\uD840-\uD869][\uDC00-\uDED6]/;
+
+function getInitialsLatin(displayName: string, isRtl: boolean): string {
+  let initials = '';
+
+  const splits: string[] = displayName.split(' ');
+
+  if (splits.length === 2) {
+    initials += splits[0].charAt(0).toUpperCase();
+    initials += splits[1].charAt(0).toUpperCase();
+  } else if (splits.length === 3) {
+    initials += splits[0].charAt(0).toUpperCase();
+    initials += splits[2].charAt(0).toUpperCase();
+  } else if (splits.length !== 0) {
+    initials += splits[0].charAt(0).toUpperCase();
+  }
+
+  if (isRtl && initials.length > 1) {
+    return initials.charAt(1) + initials.charAt(0);
+  }
+
+  return initials;
+}
+
+function cleanupDisplayName(displayName: string): string {
+  displayName = displayName.replace(UNWANTED_ENCLOSURES_REGEX, '');
+  displayName = displayName.replace(UNWANTED_CHARS_REGEX, '');
+  displayName = displayName.replace(MULTIPLE_WHITESPACES_REGEX, ' ');
+  displayName = displayName.trim();
+
+  return displayName;
+}
+
+/**
+ * Get (up to 2 characters) initials based on display name of the persona.
+ *
+ * @param displayName - The full name of the person or entity
+ * @param isRtl - Whether the display is in RTL
+ * @param allowPhoneInitials - Should initials be generated from phone numbers (default false)
+ *
+ * @returns The 1 or 2 character initials based on the name. Or an empty string if no initials
+ * could be derived from the name.
+ */
+export function getInitials(displayName: string | undefined | null, isRtl: boolean, allowPhoneInitials?: boolean): string {
+  if (!displayName) {
+    return '';
+  }
+
+  displayName = cleanupDisplayName(displayName);
+
+  // For names containing CJK characters, and phone numbers, we don't display initials
+  if (UNSUPPORTED_TEXT_REGEX.test(displayName) || (!allowPhoneInitials && PHONENUMBER_REGEX.test(displayName))) {
+    return '';
+  }
+
+  return getInitialsLatin(displayName, isRtl);
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { getInitials } from './getInitials';

package/tsconfig.json

@@ -1,7 +1,8 @@
 {
   "extends": "@fluentui-react-native/scripts/tsconfig.json",
   "compilerOptions": {
-    "outDir": "lib"
+    "outDir": "lib",
+    "types": ["node", "jest"]
   },
   "include": ["src"]
 }