ragflow-pagination.stories.ts

Overview

This file defines Storybook stories for the RAGFlowPagination React component, which is a UI pagination control designed to facilitate navigation through large datasets by dividing content into pages. The stories provide a sandbox environment for developers and designers to visualize, interact with, and document the component's behavior and appearance.

The file leverages Storybook's modern configuration with:

• A default export meta object describing the component and its Storybook metadata.

• One example story named WithLoading that demonstrates typical usage with loading and page size changing features.

Detailed Breakdown

1. Imports

import type { Meta, StoryObj } from '@storybook/react-webpack5';
import { fn } from 'storybook/test';
import { RAGFlowPagination } from '@/components/ui/ragflow-pagination';

• Meta, StoryObj: Types to strongly type Storybook metadata and story objects.

• fn: A Storybook utility function to spy on callbacks for action logging.

• RAGFlowPagination: The pagination component under test.

2. Storybook Metadata (meta)

const meta = {
  title: 'Example/RAGFlowPagination',
  component: RAGFlowPagination,
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: `
## Component Description

RAGFlowPagination is a pagination component that helps navigate through large datasets by dividing them into pages. It provides intuitive controls for users to move between pages, adjust page size, and view their current position within the dataset.`,
      },
    },
  },
  tags: ['autodocs'],
  argTypes: {
    current: { control: 'number' },
    pageSize: { control: 'number' },
    total: { control: 'number' },
  },
  args: { onChange: fn() },
} satisfies Meta<typeof RAGFlowPagination>;

• title: Categorizes the story inside Storybook's UI under "Example/RAGFlowPagination".

• component: Points to the actual React component.

• parameters:

  • layout: 'centered' centers the component in Storybook's canvas.

  • docs.description.component provides Markdown documentation shown in Storybook Docs.

• tags: autodocs enables automatic documentation generation.

• argTypes: Defines controls for current, pageSize, and total props to allow interactive manipulation.

• args: Sets a default onChange callback wrapped by Storybook's action logger (fn()).

3. Type Aliases

type Story = StoryObj<typeof meta>;

Defines the Story type to be used for all stories consistent with the defined meta.

4. Story: WithLoading

export const WithLoading: Story = {
  args: {
    current: 1,
    pageSize: 10,
    total: 100,
    showSizeChanger: true,
  },
  parameters: {
    docs: {
      description: {
        story: `
### Usage Examples

\`\`\`tsx
import { RAGFlowPagination } from '@/components/ui/ragflow-pagination';

  <RAGFlowPagination
    {...pick(pagination, 'current', 'pageSize')}
    total={pagination.total}
    onChange={(page, pageSize) => {
      setPagination({ page, pageSize });
    }}>
  </RAGFlowPagination>
\`\`\`
        `,
      },
    },
  },
  tags: ['!dev'],
};

• args:

  • current: The current page index (starting at 1).

  • pageSize: Number of items per page.

  • total: Total number of items across all pages.

  • showSizeChanger: Enables a UI control to change the page size dynamically.

• parameters.docs.description.story: Provides a usage example in TypeScript React syntax demonstrating a typical controlled pagination setup.

• tags: !dev likely marks this story for exclusion from development-focused filters.

Important Implementation Details

• This file is purely for Storybook documentation and does not implement the pagination logic itself.

• The pagination component RAGFlowPagination is imported from the UI components directory and is expected to handle:

  • Displaying page numbers.

  • Handling user input for page navigation.

  • Allowing dynamic page size changes if showSizeChanger is true.

• The onChange handler receives new page and page size values for controlling pagination state externally.

Interaction with Other System Parts

• RAGFlowPagination Component: The main interactive UI component imported from the project source.

• Storybook Environment: This file integrates the component into Storybook, enabling isolated UI testing, documentation, and prop control.

• Test Utilities (fn): Used to track callback invocations in the Storybook UI.

This file does not affect runtime application logic but serves as a development and documentation tool to improve component usability and consistency.

Usage Example Summary

import { RAGFlowPagination } from '@/components/ui/ragflow-pagination';

const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 100 });

<RAGFlowPagination
  current={pagination.current}
  pageSize={pagination.pageSize}
  total={pagination.total}
  onChange={(page, pageSize) => setPagination({ current: page, pageSize })}
/>

This pattern lets the parent component fully control pagination state while allowing the user to interact through the RAGFlowPagination UI.

Visual Diagram

flowchart TD
    A[RAGFlowPagination Stories File]
    A --> B[Meta Configuration]
    A --> C[Story: WithLoading]

    B --> D[title: string]
    B --> E[component: RAGFlowPagination]
    B --> F[argTypes: controls for current, pageSize, total]
    B --> G[args: default onChange = fn()]

    C --> H[args: current, pageSize, total, showSizeChanger]
    C --> I[parameters.docs.description.story (usage example)]
    C --> J[tags: !dev]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1px
    style C fill:#bbf,stroke:#333,stroke-width:1px

Summary

ragflow-pagination.stories.ts provides a well-structured Storybook configuration for the RAGFlowPagination component. It documents the component's purpose, exposes interactive controls for key props, and offers usage examples to assist developers in integrating pagination controls into their applications. The file enhances component discoverability and usability during UI development without involving actual logic implementation.