Revert "Revert "Update avatar documentation (#987)""

This reverts commit d908ad7.

Author: danoc

next/images/pages/components/avatar/android/online-indicator.png

@@ -0,0 +1,196 @@
+import { MDXComponentPage } from '../../../components/mdx/mdx';
+import baseGetStaticProps from '../../../utils/mdx-get-static-props';
+export const getStaticProps = ctx => baseGetStaticProps(ctx, metadata);
+export default props => <MDXComponentPage {...props} {...metadata} />;
+
+export const metadata = {
+    title: 'Avatar',
+    description: 'Display user images and badges on Thumbtack.',
+    component: {
+        id: 'avatar',
+        platformId: 'android',
+    },
+};
+
+import { Img } from '../../../components/mdx/components';
+
+import variations from '../../../images/pages/components/avatar/android/variations.png';
+import sizes from '../../../images/pages/components/avatar/android/sizes.png';
+import withoutImages from '../../../images/pages/components/avatar/android/without-images.png';
+import onlineIndicator from '../../../images/pages/components/avatar/android/online-indicator.png';
+
+## Avatar variations
+
+Avatars can be placed in your layout files as either: `EntityAvatarView` or `UserAvatarView`.
+
+<Img
+    {...variations}
+    className="db mw7 m_h-auto"
+    fill={false}
+    alt="Screenshot of both Avatar types"
+></Img>
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    android:id="@+id/variationEntity"
+    style="@style/avatarExtraLarge" />
+```
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    android:id="@+id/variationUser"
+    style="@style/avatarExtraLarge"/>
+```
+
+```java
+variationEntity.bind(imageUrl = NICOLAS_CAGE_URL, initials = "N")
+variationUser.bind(imageUrl = NICOLAS_CAGE_URL, initials = "NC")
+```
+
+`UserAvatarView` is for people or users whereas `EntityAvatarView` is for companies, businesses, or services.
+
+Note that image URLs and avatar initials are _not_ specified in the layout; those are specified in the avatar's `.bind()` method.
+
+```java
+/**
+* Begins loading the image from the given [imageUrl], positions and sizes the online badge,
+* sets its visiblity based on [isOnline], and create a [BlankAvatarDrawable] as the
+* fallback avatar. The [BlankAvatarDrawable] will contain the string [initials] and use the
+* colors specified in [BlankAvatarDrawable.setColorsFromInitials], which maps the first letter
+* of [initials] to background and text color values.
+*
+* If no [imageUrl] is given, or if there is an error fetching the image, then the
+* [BlankAvatarDrawable] created from [initials] will be displayed. A gray placeholder is shown
+* during the image's loading if an [imageUrl] is specified.
+*
+* If both [imageUrl] and [initials] are unspecified, no avatar will be displayed.
+*
+* As specified in Thumbprint style guides, entity avatars should pass in one letter
+* for [initials] and user avatars should pass in two letters for [initials].
+*/
+fun bind(imageUrl: String? = null, initials: String? = null, isOnline: Boolean = false) {
+    ...
+}
+```
+
+## Avatar sizes
+
+Both `UserAvatarView` and `EntityAvatarView` are available in five sizes ranging from `avatarExtraLarge` to `avatarExtraSmall`.
+
+<Img {...sizes} className="db mw7 m_h-auto" fill={false} alt="Avatar sizes"></Img>
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    style="@style/avatarExtraLarge"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    style="@style/avatarLarge"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    style="@style/avatarMedium"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    style="@style/avatarSmall"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.UserAvatarView
+    style="@style/avatarExtraSmall"/>
+```
+
+---
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    style="@style/avatarExtraLarge"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    style="@style/avatarLarge"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    style="@style/avatarMedium"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    style="@style/avatarSmall"/>
+```
+
+```xml
+<com.thumbtack.thumbprint.views.EntityAvatarView
+    style="@style/avatarExtraSmall"/>
+```
+
+## Avatars without images
+
+Avatars without images can display the the user or entity’s initials instead. The initials and background colors are assigned based on the first letter in the `initials` parameter of the `.bind()` method.
+
+<Img {...withoutImages} className="db mw7 m_h-auto" fill={false} alt="Avatar Without Images"></Img>
+
+```xml
+<LinearLayout
+    android:id="@+id/noImagesUser"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:orientation="horizontal"
+    android:gravity="center">
+
+    <com.thumbtack.thumbprint.views.UserAvatarView
+        style="@style/avatarMedium"/>
+        ...
+
+</LinearLayout>
+```
+
+```xml
+<LinearLayout
+    android:id="@+id/noImagesEntity"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:orientation="horizontal"
+    android:gravity="center">
+
+    <com.thumbtack.thumbprint.views.EntityAvatarView
+        style="@style/avatarMedium"/>
+        ...
+
+</LinearLayout>
+```
+
+```java
+var letters = sequenceOf("A", "B", "C", "D", "E", "F").iterator()
+noImagesUser.forEachChild {
+    (it as? UserAvatarView)?.bind(imageUrl = null, initials = letters.next() + "A")
+}
+
+letters = sequenceOf("A", "B", "C", "D", "E", "F").iterator()
+noImagesEntity.forEachChild {
+    (it as? EntityAvatarView)?.bind(imageUrl = null, initials = letters.next())
+}
+```
+
+### Online
+
+This badge indicates that a user or entity is online. It can be set initially through the `.bind()` method, or dynamically through the `setIsOnline()` method.
+
+<Img {...onlineIndicator} className="db mw7 m_h-auto" fill={false} alt="Avatar badges"></Img>
+
+```java
+badgesUser.forEachChild {
+    (it as? UserAvatarView)?.bind(imageUrl = NICOLAS_CAGE_URL, isOnline = true)
+}
+
+badgesEntity.forEachChild {
+    (it as? EntityAvatarView)?.bind(imageUrl = NICOLAS_CAGE_URL, isOnline = true)
+}
+```

next/images/pages/components/avatar/android/sizes.png

@@ -0,0 +1,84 @@
+import { MDXComponentPage } from '../../../components/mdx/mdx';
+import baseGetStaticProps from '../../../utils/mdx-get-static-props';
+export const getStaticProps = ctx => baseGetStaticProps(ctx, metadata);
+export default props => <MDXComponentPage {...props} {...metadata} />;
+
+export const metadata = {
+    title: 'Avatar',
+    description: 'Display user images and badges on Thumbtack.',
+    component: {
+        id: 'avatar',
+        platformId: 'ios',
+    },
+};
+
+import { Img } from '../../../components/mdx/components';
+
+import avatarOnlineNow from '../../../images/pages/components/avatar/ios/online-now.png';
+import avatarVariations from '../../../images/pages/components/avatar/ios/variations.png';
+
+## Summary
+
+Avatars provide a container for displaying Entity or User images on Thumbtack. This `UIView` container displays either the filled images after loading the image via URL or the blank Avatar view if there’s no backing image and initials are provided.
+
+Use `EntityAvatar` or `UserAvatar` classes directly depending on the object to be displayed.
+
+<div>
+    <b>Entity</b>: a company, business, or service.
+</div>
+
+<div>
+    <b>User</b>: a person or user.
+</div>
+
+<Img {...avatarVariations} className="db mw6 m_h-auto" fill={false}></Img>
+
+```swift
+let entityAvatar = EntityAvatar(size: .medium)
+entityAvatar.name = "Nicolas Cage"
+entityAvatar.initials = "NC"
+entityAvatar.setImageURL(avatarImageURL)
+
+let userAvatar = UserAvatar(size: .medium)
+userAvatar.name = "Nicolas Cage"
+userAvatar.initials = "NC"
+userAvatar.setImageURL(avatarImageURL)
+```
+
+## Accessibility
+
+Provide the `name` property to override the view’s accessibility label. If not provided, the accessibility label will be `nil`.
+
+## Public API
+
+### `public var image: UIImage?`
+
+The image displayed in the avatar image view.
+
+### `public var size: Avatar.Size`
+
+One of the provided avatar sizes: `xSmall`, `small`, `medium`, `large`, `xLarge`
+
+### `public var isOnline: Bool`
+
+Boolean value that controls whether the online badge is shown or not.
+
+<Img {...avatarOnlineNow} className="db mw6 m_h-auto" fill={false}></Img>
+
+### `public var initials: String?`
+
+The initials to be shown when displaying the blank avatar. Any string longer than one character will be truncated for display.
+
+### `public var name: String?`
+
+Used for accessibility label for the avatar.
+
+### `public init(size: Avatar.Size, initials: String? = nil, name: String? = nil, isOnline: Bool = false)`
+
+Initializes an EntityAvatar/UserAvatar. Parameters: size: The initial `Avatar.Size` class for the component. initials: Any string longer that one character will be truncated for display. name: Used for accessibility label for the avatar.
+
+_Note_ A URL extension is provided for utility for loading a remote image. It is not part of the core Thumbprint API as it relies on SDWebImage.
+
+### `func setImageURL(_ url: URL?) -> SDWebImageOperation?`
+
+Loads an image from the given URL and sets a blank placeholder image while loading. Once loaded, the image is displayed in the Avatar.