@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Avatar.md

@@ -0,0 +1,298 @@
+# Avatar
+
+## Overview
+
+
+> Image: Illustration of Avatar component showing user profile representations
+
+
+## When to use this component
+Use `Avatar` to represent a user in your application interface. It provides a visual identity for users through profile pictures, initials, or icons.
+
+- To display user identity in profiles, user lists, or account settings.
+- To show who performed an action in activity feeds or comments.
+- To represent users in collaboration features or team member lists.
+- To provide visual context for user-generated content.
+
+### Additional considerations
+- Always provide a meaningful label for accessibility.
+- Use consistent sizing throughout your application.
+- Consider using initials when profile pictures are not available.
+- Ensure proper contrast between text and background colors.
+
+## When to use another component
+- For display of non-user entities like organizations or systems, use `Image`.
+- For clickable actions that aren't related to user identity, use `Button`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Avatar component or something else
+    A(Need to represent a user?) -- Yes --- B(Avatar)
+    A -- No --- C(Is it a non-identity action?)
+    C -- Yes --- D(Button)
+    C -- No --- E(Image)
+```
+
+### Check out
+- [Image][1]
+- [Button][2]
+
+## Behaviors
+
+### Interactive
+When an `onClick` handler or `to` prop is provided, the `Avatar` becomes interactive and can be clicked to navigate or trigger actions.
+
+> Image: Examples of interactive Avatars. The first example with heart eyes emoji shows an Avatar with a subtle hover state. The second example with grimacing emoji shows an Avatar without clear interactive feedback.
+
+
+### Image fallback
+When an image fails to load, the `Avatar` automatically falls back to displaying initials, providing a consistent user experience.
+
+> Image: Examples of image fallback behavior. The first example with heart eyes emoji shows an Avatar that gracefully falls back to initials when the image fails to load. The second example with grimacing emoji shows an Avatar with a broken image placeholder.
+
+
+## Usage
+
+### Size consistency
+Use consistent `Avatar` sizes throughout your application. Group related `Avatars` using the same size for visual harmony.
+
+> Image: Examples of Avatar size consistency. The first example with heart eyes emoji shows Avatars of consistent size in a user list. The second example with grimacing emoji shows Avatars of varying sizes creating visual inconsistency.
+
+
+### Color and contrast
+Ensure initials have sufficient contrast against the background color for accessibility compliance. By default, the component logic handles color contrast automatically.
+
+> Image: Examples of proper color contrast. The first example with heart eyes emoji shows Avatars with good contrast between initials and background. The second example with grimacing emoji shows Avatars with poor contrast that are difficult to read.
+
+
+## Content
+
+### Meaningful labels
+Always provide descriptive labels that clearly identify what the `Avatar` represents.
+
+> Image: Examples of meaningful Avatar labels. The first example with heart eyes emoji shows an Avatar with a clear, descriptive label like 
+
+
+### Initials best practices
+Use 1-3 characters for initials, typically the first letter of first and last names.
+
+> Image: Examples of proper initials usage. The first example with heart eyes emoji shows Avatars with appropriate 1-3 character initials. The second example with grimacing emoji shows Avatars with too many character initials.
+
+
+### Image guidelines
+Use high-quality, appropriately sized images that clearly show the person's face.
+
+> Image: Examples of proper image usage. The first example with heart eyes emoji shows an Avatar with a clear, well-framed profile picture. The second example with grimacing emoji shows an Avatar with a low-quality or inappropriate image.
+
+
+### Capitalization
+Use all caps for `Avatar` labels to ensure consistency and clarity.
+
+> Image: Examples of proper capitalization. The first example with heart eyes emoji shows an Avatar label in all caps. The second example with grimacing emoji shows an Avatar label with improper capitalization.
+
+
+[1]: ./Image
+[2]: ./Button
+
+## Examples
+
+
+### Basic
+
+An Avatar can show one to three characters. You can use the `getInitials` helper to shorten a name.
+
+```typescript
+import React from 'react';
+
+import Avatar, { getInitials } from '@splunk/react-ui/Avatar';
+import Layout from '@splunk/react-ui/Layout';
+
+
+export default function Basic() {
+    return (
+        <Layout>
+            <Avatar initials="A" label="Amelia's profile" />
+            <Avatar initials={getInitials('Amelia Earhart')} label="Amelia Earhart's profile" />
+        </Layout>
+    );
+}
+```
+
+
+
+### Image
+
+An Avatar can show an image provided as an icon, <img>, or asset.
+
+```typescript
+import React from 'react';
+
+import Portrait from '@splunk/react-icons/Portrait';
+import Avatar from '@splunk/react-ui/Avatar';
+import Layout from '@splunk/react-ui/Layout';
+
+import profilePicture from '../assets/profilePicture.png';
+
+
+export default function Image() {
+    return (
+        <Layout>
+            <Avatar
+                initials="AY"
+                image={<img src={profilePicture} alt="Anna Yang" />}
+                label="Anna Yang's profile"
+            />
+            <Avatar initials="AE" image={<Portrait />} label="Amelia Earhart's profile" />
+        </Layout>
+    );
+}
+```
+
+
+
+### Background color
+
+```typescript
+import React from 'react';
+
+import Avatar from '@splunk/react-ui/Avatar';
+import Layout from '@splunk/react-ui/Layout';
+import { pick, variables } from '@splunk/themes';
+
+const avatarColor = pick({
+    enterprise: {
+        light: variables.diverging3ColorB,
+        dark: variables.diverging1ColorA,
+    },
+    prisma: {
+        light: variables.sequential6D7,
+        dark: variables.sequential6D3,
+    },
+});
+
+
+export default function BackgroundColor() {
+    return (
+        <Layout>
+            <Avatar backgroundColor={avatarColor} initials="AE" label="Amelia Earhart's profile" />
+            <Avatar
+                backgroundColor="rgb(255, 103, 123)"
+                initials="AE"
+                label="Amelia Earhart's profile"
+            />
+            <Avatar backgroundColor="#2d2d53" initials="AE" label="Amelia Earhart's profile" />
+            <Avatar
+                backgroundColor="cornflowerblue"
+                initials="AE"
+                label="Amelia Earhart's profile"
+            />
+        </Layout>
+    );
+}
+```
+
+
+
+### Interactive
+
+Avatars can be interactive by including the appropriate props to make them buttons or links.
+
+```typescript
+import React from 'react';
+
+import Avatar from '@splunk/react-ui/Avatar';
+import Layout from '@splunk/react-ui/Layout';
+
+import profilePicture from '../assets/profilePicture.png';
+
+
+export default function Interactive() {
+    return (
+        <Layout>
+            <Avatar
+                image={<img src={profilePicture} alt="Amelia Earhart" />}
+                initials="AE"
+                label="Amelia Earhart's profile"
+                onClick={() => {}}
+            />
+            <Avatar initials="AY" label="Anna Yang's profile" to="#Interactive" />
+        </Layout>
+    );
+}
+```
+
+
+
+### Size
+
+Avatars can be one of three standard sizes: small, medium (default), or large. The size prop can also be a string if the standard size doesn't fit your use case. Note: using a non-standard size may have unexpected layouts when combined with other components.
+
+```typescript
+import React from 'react';
+
+import Avatar from '@splunk/react-ui/Avatar';
+import Layout from '@splunk/react-ui/Layout';
+
+
+export default function Size() {
+    return (
+        <Layout>
+            <Avatar initials="AE" label="Amelia Earhart's profile" size="small" />
+            <Avatar initials="AE" label="Amelia Earhart's profile" size="medium" />
+            <Avatar initials="AE" label="Amelia Earhart's profile" size="large" />
+        </Layout>
+    );
+}
+```
+
+
+
+
+## API
+
+
+### Avatar API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| backgroundColor | \| string \| Interpolation<Enterprise, OptionalThemedProps<Enterprise>> \| Interpolation<Prisma, OptionalThemedProps<Prisma>> | no |  | All CSS color definitions are supported, such as `#223344` or `red`. Using `theme` enables the theme default. |
+| elementRef | React.Ref<HTMLAnchorElement \| HTMLButtonElement \| HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and `null` when it unmounts. |
+| image | React.ReactNode | no |  | The image to be displayed inside this `Avatar`, for example an `<img>` or `<svg>`. |
+| initials | string | yes |  | The contents of this `Avatar` if the `image` prop is not set or the provided image is not valid. Must not exceed three characters in length. |
+| label | string | yes |  | Text to describe what this Avatar represents. |
+| onClick | AvatarClickHandler | no |  | Enables interactive mode. |
+| size | 'small' \| 'medium' \| 'large' \| string | no | 'medium' | Adjusts the size of the `Avatar`. |
+| to | string | no |  | If set, the component will be rendered as an `<a>` tag with `href` equal to this prop rather than a `<button>` tag. |
+| value | string | no |  | The value returned with `onClick` events, which can be used to identify the control when multiple controls share an `onClick` callback. Not to be confused with `initials`. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| AvatarClickHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: { value?: string } ) => void |  |
+
+
+
+#### Utils
+
+
+#### getInitials(name)
+
+Returns a suitable set of initials for a name. Uses the first character of each
+name segment and omits middle segments if the segment count is greater than three.
+
+##### Parameters
+
+| Name | Type | Optional | Default | Description |
+|------|------|------|------|------|
+| name | string | no |  | The full name. |
+
+##### Returns
+
+**string** - Limited to three characters. Empty if `name` is empty.
+
+
+
+

package/docs-llm/Badge.md

@@ -0,0 +1,212 @@
+# Badge
+
+## Overview
+
+
+> Image: Illustration of a group of three Badges.
+
+
+## When to use this component
+Badges serve as visual indicators used to communicate a status, numeric value, or other associated metadata of an object.
+
+- To represent a status, property, or specific metadata for an object (e.g., "New", "Beta", "Active", "Warning").
+- To display a count of associated items (e.g., number of unread messages, items in a category).
+- To visually annotate an item, drawing attention to its current state or characteristic.
+
+## When to use another component
+
+- When you need to represent input, attribute, or actions of an object, use `Chip`. 
+
+### Decision tree
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Badge component or something else
+    A(Need a visual indicator?) --- B(For labeling, categorizing,<br/>or organizing objects?)
+    A -- No --- G(Paragraph)
+    B -- Yes --- C(Chip)
+    B -- No --- D(Need multiple elements<br/>in a group?)
+    D -- Yes --- C
+    D -- No --- E(Visual indicator for status<br/>or description of an element?)
+    E -- Yes --- F(Badge)
+```
+
+
+### Check out
+-   [Chip][1]
+
+## Usage
+
+### Placement
+Badges are positioned to the side of their associated context. 
+
+> Image: Example of badge placed next to a text label.
+
+
+### Non-interactive
+Badges are non-interactive and serve purely as visual indicators.
+
+> Image: The first example with heart eyes emoji shows a badge that is non interactive. The second example with grimacing emoji shows the badge with hover indicating it can be clicked.
+
+
+### Standalone
+Do not use multiple badges for similar type of page or object annotations, such as "new," "updated," or "experimental."
+
+> Image: The first example with heart eyes emoji shows a heading with a single badge next to it. The second example with grimacing emoji shows a heading with mutliple badges that represent similar type of information next to it.
+
+
+### Grouping Multiple Badges
+In scenarios where an object has multiple concurrent states or properties, such as an incident that is "active", critically "severe", and "AI-detected", displaying multiple badges together is appropriate. Grouping badges allows each distinct property to be visually represented without conflating their meanings. Avoid overloading the interface with excessive badges; prioritize the most relevant states (tyipcally 1-3) for display.
+
+> Image: The first example with heart eyes emoji shows a heading with a distinct badges. The second example with grimacing emoji shows a heading with a large number of badges next to it.
+
+
+### Count Handling
+
+#### Showing Zero '0'
+Badges with a zero count should generally not be rendered to avoid unnecessary visual noise. However, there are specific instances where explicitly showing '0' is relevant and provides meaningful context (e.g., indicating "no alerts" or "zero items in a list"). 
+
+> Image: The first example with heart eyes emoji shows a heading with no badge, indicating no objects. The second example with grimacing emoji shows heading with a badge with count zero.
+
+
+
+#### Max count
+When a count exceeds a certain threshold, it is often more effective to display a maximum value (e.g., '99+') rather than the exact large number. To achieve this, use the `truncateNumber` utility from `@splunk/ui-utils`.
+
+> Image: The first example with heart eyes emoji shows a heading with badge that shows a max count of 
+
+
+## Content
+
+### Write concise labels: 1-3 words
+Badges should provide concise information. For text-based Badges, keep the text brief and descriptive. When using icons, ensure they clearly communicate the status or description. 
+
+> Image: The first example with heart eyes emoji shows a badge with concise text. The second example with grimacing emoji shows a badge with very lengthy text.
+
+
+### Follow color contrast guidelines
+When using custom colors, ensure you are following the WCAG guideline of a contrast ratio &gt= 4.5:1 between text and background. [SC 1.4.3][2]
+
+> Image: Example of a badge with custom colours. In the first example with heart eyes, the badge label is dark and abide by the 4.5 to 1 contrast guidelines. In the second example with the grimacing face, the badge label is similar to the background colours, breaking the contrast guidelines.
+
+
+
+[1]: ./Chip
+[2]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React from 'react';
+
+import Badge from '@splunk/react-ui/Badge';
+
+
+export default function Basic() {
+    return <Badge label="Beta" />;
+}
+```
+
+
+
+### Count
+
+To set a max count, use the `truncateNumber` util from [@splunk/ui-utils](../ui-utils/Format).
+
+```typescript
+import React from 'react';
+
+import Badge from '@splunk/react-ui/Badge';
+import Layout from '@splunk/react-ui/Layout';
+import { truncateNumber } from '@splunk/ui-utils/format';
+
+
+export default function Count() {
+    const count = truncateNumber({ number: 110, max: 99 });
+
+    return (
+        <Layout>
+            <Badge label="5" />
+            <Badge label={count} />
+        </Layout>
+    );
+}
+```
+
+
+
+### With icons
+
+Use the `icon` prop with an icon component (e.g., `@splunk/react-icons`) to add visual context or emphasis alongside the badge's `label`. When using an icon, a label must also be provided.
+
+```typescript
+import React from 'react';
+
+import Lightbulb from '@splunk/react-icons/Lightbulb';
+import Badge from '@splunk/react-ui/Badge';
+
+
+export default function Icon() {
+    return <Badge icon={<Lightbulb />} label="Beta" />;
+}
+```
+
+
+
+### Custom colors
+
+The background and text of Badge can be customized with the `backgroundColor` and `foregroundColor` props. Prefer using variables from `@splunk/themes`, but other valid CSS color values are supported. In all cases, you must check that the chosen colors meet [contrast minimum for text of 4.5:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html#user%20interface%20component).
+
+```typescript
+import React from 'react';
+
+import Badge from '@splunk/react-ui/Badge';
+import Layout from '@splunk/react-ui/Layout';
+import { variables } from '@splunk/themes';
+
+
+export default function CustomColors() {
+    return (
+        <Layout>
+            <Badge
+                label="RGB"
+                backgroundColor="rgb(255, 135, 139)"
+                foregroundColor="rgb(0, 0, 0, 0.9)"
+            />
+            <Badge label="Hexcode" backgroundColor="#1AB2FF" foregroundColor="#000" />
+            <Badge
+                label="Variables"
+                backgroundColor={variables.notificationColorPositive}
+                foregroundColor={variables.contentColorInverted}
+            />
+            <Badge label="Named Colors" backgroundColor="cornflowerblue" foregroundColor="black" />
+        </Layout>
+    );
+}
+```
+
+
+
+
+## API
+
+
+### Badge API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| backgroundColor | \| React.CSSProperties['color'] \| Interpolation<AnyTheme, OptionalThemedProps<AnyTheme>> | no |  | Changes the background color. Accepts `@splunk/themes` variable or any valid `color` value. |
+| elementRef | React.Ref<HTMLSpanElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| foregroundColor | \| React.CSSProperties['color'] \| Interpolation<AnyTheme, OptionalThemedProps<AnyTheme>> | no |  | Changes the text and icon color. Accepts `@splunk/themes` variable or any valid `color` value. |
+| icon | React.ReactNode | no |  | Icon before the label. |
+| label | string | yes |  | The content of the badge. |
+
+
+
+
+