button-loading.stories.ts

Overview

button-loading.stories.ts is a Storybook story definition file for the ButtonLoading React component. It serves as a showcase and documentation tool for the ButtonLoading component within a Storybook environment. The file sets up metadata, controls, and example scenarios (stories) that demonstrate how ButtonLoading behaves, especially focusing on its loading state.

This file enables developers and designers to visualize, interact with, and understand the usage of the ButtonLoading component in isolation, improving component discoverability and facilitating UI testing.

Detailed Explanation

Imports

• Meta, StoryObj from @storybook/react-webpack5:
  Types and utilities for defining Storybook metadata and stories in TypeScript.

• fn from storybook/test:
  A utility to create function spies for event handlers, enabling interactive action logging in Storybook.

• ButtonLoading from @/components/ui/button:
  The React component this story is written for, which is a button with a loading animation/state.

Meta Object (meta)

Defines the metadata and configuration for the ButtonLoading component stories.

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

ButtonLoading is a button component with a loading state and supports displaying loading animation.
        `,
      },
    },
  },
  tags: ['autodocs'],
  argTypes: {
    loading: { control: 'boolean' },
  },
  args: { onClick: fn() },
} satisfies Meta<typeof ButtonLoading>;

• title: Organizes the story in the Storybook UI under Example/ButtonLoading.

• component: Specifies the component to render in the story.

• parameters:

  • layout: 'centered' ensures the component is centered in the preview canvas.

  • docs.description.component provides documentation text for the component in the Docs tab.

• tags: ['autodocs'] enables automatic documentation generation.

• argTypes: Defines controls and knobs for interacting with component properties in Storybook UI. Here, loading is a boolean toggle.

• args: Default arguments for all stories; here, the onClick handler is spied on via fn() so clicks are logged in Storybook's actions panel.

Exported Story: WithLoading

export const WithLoading: Story = {
  args: {
    loading: true,
    children: 'Button',
  },
  parameters: {
    docs: {
      description: {
        story: `
### Usage Examples

\`\`\`tsx
import { ButtonLoading } from '@/components/ui/button';

<ButtonLoading loading={true}>
  Loading Button
</ButtonLoading>
\`\`\`
        `,
      },
    },
  },
  tags: ['!dev'],
};

• Represents a usage example where the button is in a loading state (loading: true).

• children: 'Button' sets the button text.

• Additional documentation snippet shows example usage in TypeScript JSX.

• The story is tagged with !dev to exclude it from development-only story groups.

Usage Example

In Storybook UI, users can interact with the WithLoading story to see how the ButtonLoading component looks and behaves when loading. The loading control allows toggling the loading state on and off dynamically.

Example JSX usage extracted from the story docs:

import { ButtonLoading } from '@/components/ui/button';

<ButtonLoading loading={true}>
  Loading Button
</ButtonLoading>

Implementation Details

• The file leverages Storybook's TypeScript types and satisfies keyword to ensure the meta object conforms exactly to the expected Meta type for the ButtonLoading component.

• Uses Storybook controls (argTypes) to allow interactive toggling of the loading prop.

• Uses fn() from storybook/test to spy on the onClick event, enabling action logging in Storybook’s Actions panel.

• The story organizes documentation into two places: the component-level description (shown in Docs tab) and story-level usage examples.

• The layout: 'centered' parameter centers the component in the Storybook preview, improving visual presentation.

Interaction with Other System Parts

• ButtonLoading Component (@/components/ui/button):
  This file depends on the ButtonLoading component implementation. It does not implement the component itself but documents and tests it.

• Storybook Environment:
  This file is loaded by Storybook's React Webpack 5 builder, which uses these stories to generate the interactive UI documentation.

• Test Utilities (storybook/test):
  Uses the fn utility to create event handler spies for interaction tracking.

Mermaid Diagram: Story Structure Flowchart

flowchart TD
    A[button-loading.stories.ts]
    A --> B[Meta Configuration]
    B --> B1[title: 'Example/ButtonLoading']
    B --> B2[component: ButtonLoading]
    B --> B3[parameters]
    B3 --> B3a[layout: 'centered']
    B3 --> B3b[docs.description.component]
    B --> B4[argTypes: loading (boolean)]
    B --> B5[args: onClick fn()]

    A --> C[Story: WithLoading]
    C --> C1[args: loading = true, children = 'Button']
    C --> C2[parameters: docs.description.story (usage example)]
    C --> C3[tags: !dev]

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

Summary

button-loading.stories.ts is a Storybook story file that documents the ButtonLoading React component. It provides a centered display with interactive controls, action logging for clicks, and clear usage examples to assist developers in understanding and testing the button's loading state. The file uses TypeScript to enforce typing and Storybook best practices for documentation and interactivity.