ragflow-avatar.stories.ts

Overview

This file defines Storybook stories for the RAGFlowAvatar React component. The purpose is to provide an interactive documentation and testing environment that showcases various usages and states of the RAGFlowAvatar component within Storybook.

RAGFlowAvatar is a customizable avatar UI component that displays user avatars with intelligent fallbacks — showing either the user’s avatar image or generating colorful gradient backgrounds with user initials when an image is not available. This stories file demonstrates how the component behaves with different props and styles, helping developers understand and test the component quickly.

Detailed Explanation

Storybook Meta Configuration (meta)

The meta object configures the Storybook interface for the RAGFlowAvatar component:

• title: Categorizes the component under "Example/RAGFlowAvatar" in Storybook’s sidebar.

• component: References the RAGFlowAvatar component imported from @/components/ragflow-avatar.

• parameters: Customizes Storybook behavior and docs:

  • layout: 'centered' centers the component in the Canvas view.

  • docs.description.component: Provides a detailed Markdown description of the component, including import path, features, and usage examples.

• tags: Includes autodocs for automatic documentation generation.

• argTypes: Defines controls and documentation for component props:

  • name: User's name to display initials if no avatar image.

  • avatar: URL of the avatar image.

  • isPerson: Boolean determining the avatar style (circular for persons, rounded rectangle otherwise).

  • className: Optional additional CSS classes.

• args: Default prop values for stories (e.g., name: 'John Doe', isPerson: false).

Stories

Each story is a named export that demonstrates a particular use case or state of the RAGFlowAvatar component. Stories leverage Storybook's args mechanism to pass props and provide contextual documentation.

1. WithInitials

• Purpose: Shows the avatar with only a user name, rendering initials on a colorful gradient background.

• Args:

  • name: 'John Doe'

  • isPerson: false (rounded rectangle style)

• Docs: Includes a code snippet demonstrating usage.

• Use Case: When no avatar image is provided and the avatar represents a non-person entity or bot.

<RAGFlowAvatar
  name="John Doe"
  isPerson={false}
/>

2. WithAvatar

• Purpose: Shows the avatar displaying an actual image.

• Args:

  • name: 'Jane Smith'

  • avatar: A Base64 SVG image string (simulating an image URL).

  • isPerson: true (circular style)

• Docs: Provides usage example with an avatar URL.

• Use Case: When a user image is available and the avatar represents a person.

<RAGFlowAvatar
  name="Jane Smith"
  avatar="https://example.com/avatar.jpg"
  isPerson={true}
/>

3. PersonStyle

• Purpose: Highlights the circular style for person avatars.

• Args:

  • name: 'Alice Johnson'

  • isPerson: true

• Use Case: Emphasizes the circular styling applied when isPerson is true.

4. NonPersonStyle

• Purpose: Shows the rounded rectangle style for non-person avatars.

• Args:

  • name: 'Bot Assistant'

  • isPerson: false

• Use Case: Demonstrates the alternative styling when the avatar does not represent a person (e.g., bots, services).

Important Implementation Details and Algorithms (Inferred)

While this file itself does not contain the component implementation, the documentation embedded within the meta parameters describes some implementation details of RAGFlowAvatar:

• Initials Generation: Extracts initials from the provided name and displays them when no avatar image is available.

• Gradient Backgrounds: Generates colorful gradients based on the user’s name, ensuring consistent but unique appearance per user.

• Responsive Font Size: Uses automatic font size calculation based on container size for readability.

• Shape Variation: Switches between circular (person) and rounded rectangle (non-person) styles based on the isPerson prop.

• Resize Observer: Reactively adjusts layout or font size on container size changes.

These features are crucial for consistent UI/UX and are showcased through the stories.

Interaction with Other Parts of the System

• Component Import: This file imports RAGFlowAvatar from the @/components/ragflow-avatar module, indicating that it directly documents and tests this UI component.

• Storybook Integration: This file integrates with Storybook (using @storybook/react-webpack5), a tool widely used for component-driven development and documentation.

• Documentation: The docs.description.component field contributes to the Storybook Docs tab, enhancing developer understanding without needing to read source code.

• Usage by Developers: Developers can run Storybook to interactively preview the avatar component’s behavior, modify props via controls, and copy usage snippets.

Usage Examples Summary

// Basic usage with initials and no image
<RAGFlowAvatar name="John Doe" isPerson={false} />

// Usage with avatar image and circular style
<RAGFlowAvatar
  name="Jane Smith"
  avatar="https://example.com/avatar.jpg"
  isPerson={true}
/>

// Person style (circular)
<RAGFlowAvatar name="Alice Johnson" isPerson={true} />

// Non-person style (rounded rectangle)
<RAGFlowAvatar name="Bot Assistant" isPerson={false} />

Mermaid Diagram

The diagram below illustrates the structure of this Storybook stories file, focusing on the main Storybook meta configuration and the individual stories with their props.

flowchart TD
    Meta["Meta (Storybook Configuration)"]
    WithInitials["Story: WithInitials"]
    WithAvatar["Story: WithAvatar"]
    PersonStyle["Story: PersonStyle"]
    NonPersonStyle["Story: NonPersonStyle"]

    Meta --> WithInitials
    Meta --> WithAvatar
    Meta --> PersonStyle
    Meta --> NonPersonStyle

    subgraph MetaDetails
      direction TB
      title["title: 'Example/RAGFlowAvatar'"]
      component["component: RAGFlowAvatar"]
      parameters["parameters: layout, docs, etc."]
      argTypes["argTypes: name, avatar, isPerson, className"]
      args["args: { name: 'John Doe', isPerson: false }"]
    end

    Meta --> MetaDetails

    subgraph StoryArgs
      direction TB
      WIArgs["args: { name: 'John Doe', isPerson: false }"]
      WAArgs["args: { name: 'Jane Smith', avatar: '...', isPerson: true }"]
      PSArgs["args: { name: 'Alice Johnson', isPerson: true }"]
      NPSArgs["args: { name: 'Bot Assistant', isPerson: false }"]
    end

    WithInitials --> WIArgs
    WithAvatar --> WAArgs
    PersonStyle --> PSArgs
    NonPersonStyle --> NPSArgs

Summary

This Storybook stories file is a crucial tool for:

• Documenting the RAGFlowAvatar component’s props, features, and usage patterns.

• Providing interactive, visual demonstrations of the avatar in different states (initials-only, with image, person vs. non-person styles).

• Helping developers quickly understand and test the avatar component within the Storybook environment.

It does not contain component logic but richly documents usage scenarios and integrates tightly with Storybook for UI component development workflows.