feat(*): improve docs and refactor

Author: minheq

docs/CustomizeTheme.mdx

@@ -43,7 +43,7 @@ import { ThemeProvider } from 'paramount-ui'
 
 ## Components
 
-In the same `ThemeProvider` as above, use `components` option. For available style options for each component, see `getStyles` callback in corresponding component docs
+In the same `ThemeProvider` as above, use `components` option. See `Customization` section in corresponding component docs
 
 ```
 import { ThemeProvider } from 'paramount-ui'
@@ -91,7 +91,7 @@ import { ThemeProvider } from 'paramount-ui'
 
 ## Component Instance
 
-Each component exposes `getStyles` callback, which can be used to override component styles. This prop takes highest precedence in styling a component
+Each component exposes `getStyles` callback, which can be used to override component styles. See `Customization` section in corresponding component docs
 
 ```
 import { Button } from 'paramount-ui'

src/components/Alert/Alert.mdx

@@ -13,34 +13,39 @@ Give feedback to the user about an action or state
 ### Usage
 
 <Playground>
-  <Alert
-    title="Title"
-    description="Message"
-    intent="success"
-    getStyles={(props, theme) => ({
-      bodyStyle: {},
-      containerStyle: {},
-    })}
-  />
-</Playground>
-
-### Variants
-
-<Playground>
-  <Box paddingVertical={16}>
+  <Box paddingVertical={8}>
     <Alert title="Info" description="Message" />
   </Box>
-  <Box paddingVertical={16}>
+  <Box paddingVertical={8}>
     <Alert intent="success" title="Success" description="Message" />
   </Box>
-  <Box paddingVertical={16}>
+  <Box paddingVertical={8}>
     <Alert intent="warning" title="Warning" description="Message" />
   </Box>
-  <Box paddingVertical={16}>
+  <Box paddingVertical={8}>
     <Alert intent="danger" title="Danger" description="Message" />
   </Box>
 </Playground>
 
+### Customization
+
+Use `getStyles` prop
+
+```
+AlertStyleProps {
+  intent: Intent;
+}
+
+AlertStyles {
+  containerStyle: ViewStyle;
+  bodyStyle: ViewStyle;
+  titleStyle: TextStyle;
+  descriptionStyle: TextStyle;
+}
+
+getStyles={(AlertStyleProps, Theme) => AlertStyles}
+```
+
 ### Props
 
 <Props of={Alert} />

src/components/Alert/Alert.styles.ts

@@ -7,7 +7,7 @@ export interface AlertStyles {
   containerStyle: ViewStyle;
   bodyStyle: ViewStyle;
   titleStyle: TextStyle;
-  textStyle: TextStyle;
+  descriptionStyle: TextStyle;
 }
 
 export interface AlertStyleProps {
@@ -34,7 +34,7 @@ export const getAlertStyles: GetAlertStyles = ({ intent }, theme) => {
       padding: 16,
       ...theme.elevations[2],
     },
-    textStyle: {},
+    descriptionStyle: {},
     titleStyle: {},
   };
 };

src/components/Alert/Alert.tsx

@@ -14,22 +14,21 @@ import { AlertStyles, GetAlertStyles, getAlertStyles } from './Alert.styles';
  * Alert properties
  */
 export interface AlertProps {
-  /** Title of the alert */
+  /** Title of the alert. */
   title?: string;
-  /** Description of the alert */
+  /** Description of the alert. */
   description?: string;
-  /** Used to locate this view in end-to-end tests */
-  testID?: string;
-  /** Replace the icon of the alert on the left */
+  /** Replace the icon of the alert on the left. Set to null to remove icon */
   icon?: React.ReactNode;
   /**
-   * Intent of the alert
+   * Intent of the alert.
    * @default info
    */
   intent?: Intent;
-
-  /** Callback to get element styles */
+  /** Callback to get element styles. */
   getStyles?: ReplaceReturnType<GetAlertStyles, DeepPartial<AlertStyles>>;
+  /** Used to locate this view in end-to-end tests. */
+  testID?: string;
 }
 
 const resolveIcon = (intent: Intent) => {
@@ -60,22 +59,32 @@ export const Alert = (props: AlertProps) => {
 
   const theme = useTheme();
 
-  const { containerStyle, bodyStyle } = mergeStyles(
-    getAlertStyles,
-    getStyles,
-    theme.components.getAlertStyles,
-  )({ intent }, theme);
+  const {
+    containerStyle,
+    bodyStyle,
+    descriptionStyle,
+    titleStyle,
+  } = mergeStyles(getAlertStyles, getStyles, theme.components.getAlertStyles)(
+    { intent },
+    theme,
+  );
 
   return (
     <View style={containerStyle} testID={testID}>
-      {icon || (
-        <Box paddingRight={16} justifyContent="center">
-          {resolveIcon(intent)}
-        </Box>
-      )}
+      {icon === null
+        ? null
+        : icon || (
+            <Box paddingRight={16} justifyContent="center">
+              {resolveIcon(intent)}
+            </Box>
+          )}
       <View style={bodyStyle}>
-        <Text weight="bold">{title}</Text>
-        <Text>{description}</Text>
+        <Text getStyles={() => ({ textStyle: titleStyle })} weight="bold">
+          {title}
+        </Text>
+        <Text getStyles={() => ({ textStyle: descriptionStyle })}>
+          {description}
+        </Text>
       </View>
     </View>
   );

src/components/Avatar/Avatar.mdx

@@ -4,35 +4,43 @@ menu: Components
 ---
 
 import { Playground, Props } from 'docz';
-import { Avatar } from '..';
+import { Avatar, Box } from '..';
 
 # Avatar
 
+Display avatar image, with default for name initials
+
 ### Usage
 
 <Playground>
   <Avatar
+    source={{ uri: 'https://picsum.photos/100/100', width: 100, height: 100 }}
+    // Defaults to name if source is not provided
     name="Bill Gates"
-    source={{ uri: 'https://picsum.photos/200/200' }}
-    size={40}
-    isSolid={false}
-    color="automatic"
-    getInitials={(name, fallback) =>
-      name ? `${name.charAt(0)}${name.charAt(5)}` : 'A'
-    }
-    getStyles={(props, theme) => ({
-      boxStyle: {},
-      textStyle: {},
-      imageStyle: {},
-    })}
   />
 </Playground>
 
-### Automatic name usage
+### Customization
 
-<Playground>
-  <Avatar name="Bill Gates" />
-</Playground>
+Using `getStyles` prop
+
+```
+AvatarStylesProps {
+  name?: string;
+  color: AvatarColor;
+  isSolid: boolean;
+  size: number;
+  sizeLimitOneCharacter: number;
+}
+
+AvatarStyles {
+  containerStyle: ViewStyle;
+  textStyle: TextStyle;
+  imageStyle: ImageStyle;
+}
+
+getStyles={(AvatarStylesProps, Theme) => AvatarStyles}
+```
 
 ### Props
 

src/components/Avatar/Avatar.styles.ts

@@ -23,7 +23,6 @@ export type AvatarColor = 'automatic' | keyof FillColors;
 export interface AvatarStylesProps {
   name?: string;
   color: AvatarColor;
-  hashValue?: string;
   isSolid: boolean;
   size: number;
   sizeLimitOneCharacter: number;
@@ -74,13 +73,13 @@ export type GetAvatarStyles = (
 ) => AvatarStyles;
 
 export const getAvatarStyles: GetAvatarStyles = (
-  { name, color, hashValue, isSolid, size = 24, sizeLimitOneCharacter = 20 },
+  { name, color, isSolid, size = 24, sizeLimitOneCharacter = 20 },
   theme,
 ) => {
   let colorProps;
   const fills = theme.fills;
   if (color === 'automatic') {
-    const newHashValue = hashCode(hashValue || name);
+    const newHashValue = hashCode(name);
     colorProps = getAvatarProps(theme.fills, {
       color,
       hashValue: newHashValue,

src/components/Avatar/Avatar.tsx

@@ -3,7 +3,7 @@ import { Image, ImageSourcePropType, View } from 'react-native';
 import { DeepPartial } from 'ts-essentials';
 
 import { useTheme } from '../../theme';
-import { FillColors } from '../../theme/Theme';
+import { FillColor } from '../../theme/Theme';
 import { mergeStyles, ReplaceReturnType } from '../../utils/mergeStyles';
 import { Text } from '../Typography';
 import {
@@ -15,7 +15,7 @@ import {
 // https://github.com/segmentio/evergreen/blob/master/source/avatar/README.md
 export type GetInitialsType = (name?: string, fallback?: string) => string;
 
-const globalGetInitials: GetInitialsType = (name, fallback = '?') => {
+const getInitials: GetInitialsType = (name, fallback = '?') => {
   if (!name) return fallback;
 
   return name
@@ -27,58 +27,34 @@ const globalGetInitials: GetInitialsType = (name, fallback = '?') => {
 };
 
 export interface AvatarProps {
-  /**
-   * The source attribute of the image.
-   * When it's not available, render initials instead.
-   */
+  /** The source attribute of the image. When it's not available, render initials instead. */
   source?: ImageSourcePropType;
-
-  /**
-   * The size of the avatar.
-   */
+  /** The size of the avatar. */
   size?: number;
-
   /**
    * The name used for the initials and title attribute.
+   * @default 48
    */
   name?: string;
-
-  /**
-   * The value used for the hash function.
-   * The name is used as the hashValue by default.
-   * When dealing with anonymous users you should use the id instead.
-   */
-  hashValue?: string;
-
   /**
    * When true, render a solid avatar.
+   * @default false
    */
   isSolid?: boolean;
-
   /**
    * The color used for the avatar.
    * When the value is `automatic`, use the hash function to determine the color.
+   * @default automatic
    */
-  color?: 'automatic' | keyof FillColors;
-
-  /**
-   * Function to get the initials based on the name.
-   */
-  getInitials?: GetInitialsType;
-
-  /**
-   * When true, force show the initials.
-   * This is useful in some cases when using Gravatar and transparent pngs.
-   */
-  forceShowInitials?: boolean;
-
+  color?: 'automatic' | FillColor;
   /**
    * When the size is smaller than this number, use a single initial for the avatar.
+   * @default 20
    */
   sizeLimitOneCharacter?: number;
-
+  /** Callback to get element styles. */
   getStyles?: ReplaceReturnType<GetAvatarStyles, DeepPartial<AvatarStyles>>;
-
+  /** Used to locate this view in end-to-end tests. */
   testID?: string;
 }
 
@@ -88,19 +64,18 @@ export const Avatar = (props: AvatarProps) => {
     size = 48,
     name,
     isSolid = false,
-    hashValue,
-    getInitials = globalGetInitials,
     color = 'automatic',
-    forceShowInitials = false,
     sizeLimitOneCharacter = 20,
     getStyles,
     testID,
   } = props;
 
   const theme = useTheme();
 
-  const { imageHasFailedLoading } = { imageHasFailedLoading: false };
-  const imageUnavailable = !source || imageHasFailedLoading;
+  const [hasImageFailedLoading, setHasImageFailedLoading] = React.useState(
+    false,
+  );
+  const imageUnavailable = !source || hasImageFailedLoading;
 
   let initials = getInitials(name);
   if (size <= sizeLimitOneCharacter) {
@@ -114,7 +89,6 @@ export const Avatar = (props: AvatarProps) => {
   )(
     {
       color,
-      hashValue,
       isSolid,
       name,
       size,
@@ -125,17 +99,15 @@ export const Avatar = (props: AvatarProps) => {
 
   return (
     <View style={containerStyle} testID={testID}>
-      {(imageUnavailable || forceShowInitials) && (
-        <Text
-          getStyles={() => ({
-            textStyle,
-          })}
-        >
-          {initials}
-        </Text>
+      {imageUnavailable && (
+        <Text getStyles={() => ({ textStyle })}>{initials}</Text>
       )}
       {!imageUnavailable && !!source && (
-        <Image source={source} style={imageStyle} />
+        <Image
+          onError={() => setHasImageFailedLoading(true)}
+          source={source}
+          style={imageStyle}
+        />
       )}
     </View>
   );