import { Canvas, Meta, Story, ArgTypes} from "@storybook/addon-docs/blocks";
import { ExpandableText } from "..";
import * as ExpandableTextStories from "./ExpandableText.stories.tsx";

<Meta of={ExpandableTextStories} />

# ExpandableText

A component that displays long text with truncation and expandable functionality. It uses CSS line-clamp to limit text to a specified number of lines and provides an accordion control for expanding/collapsing the full content.

## Features

- **CSS-based truncation**: Uses modern line-clamp CSS for precise line limiting
- **Smart detection**: Automatically detects when text actually needs truncation
- **Responsive behavior**: Optional breakpoint-based truncation control
- **Accessible**: Integrates with the existing Accordion component for proper ARIA support
- **Customizable**: Configurable line limits, labels, and styling
- **Performance optimized**: Minimal DOM manipulation and efficient re-renders

## Examples

### Default

<Canvas of={ExpandableTextStories.Default} />

### Short Text (No Truncation)

When text doesn't exceed the line limit, no truncation controls are shown:

<Canvas of={ExpandableTextStories.ShortText} />

### Single Line

<Canvas of={ExpandableTextStories.SingleLine} />

### Five Lines

<Canvas of={ExpandableTextStories.FiveLines} />

### Custom Labels

<Canvas of={ExpandableTextStories.CustomLabels} />

### Responsive Truncation

This example only applies truncation on small screens. On larger screens, the full text is shown:

<Canvas of={ExpandableTextStories.WithBreakpoint} />

### Custom Text Properties

You can pass custom properties to the underlying Text component:

<Canvas of={ExpandableTextStories.WithCustomTextProps} />

## API Reference

### Props

<ArgTypes of={ExpandableText} />

## Usage Guidelines

### When to Use

- **Product descriptions** that might be lengthy
- **User-generated content** like reviews or comments
- **Article previews** or content summaries
- **Help text** that needs to be accessible but not overwhelming
- **Any long-form text** where space is limited

### When Not to Use

- **Very short text** that will never need truncation
- **Critical information** that must always be visible
- **Content with complex formatting** (currently supports plain text only)
- **Text that changes frequently** (consider performance implications)

### Best Practices

1. **Choose appropriate line limits**: 3-5 lines typically work well for most content
2. **Use clear labels**: "Read more/less" is standard, but context-specific labels can be better
3. **Consider responsive behavior**: Use breakpoint prop for mobile-first truncation
4. **Test with real content**: Ensure truncation works well with your actual text lengths
5. **Maintain consistency**: Use the same line limits and labels across similar content types

## Technical Details

### How It Works

1. **CSS Truncation**: Uses `-webkit-line-clamp` and `line-clamp` for visual truncation
2. **JavaScript Detection**: Compares `scrollHeight` vs `clientHeight` to detect overflow
3. **State Management**: Toggles CSS classes to show/hide full content
4. **Responsive Logic**: Optional breakpoint support using the Mobius breakpoint system

### Performance Considerations

- Minimal DOM manipulation (only CSS class changes)
- Efficient overflow detection using native browser APIs
- Lazy accordion rendering (only shows when needed)
- CSS-only visual changes for smooth interactions

### Browser Support

- Modern browsers with CSS line-clamp support
- Graceful degradation for older browsers (shows full text)
- Works with all Mobius-supported devices and screen sizes

## Accessibility

- Uses the existing Accordion component for proper ARIA support
- Screen readers can access the full text content
- Keyboard navigation works as expected
- Respects user preferences for reduced motion (via Accordion)

## Examples in Practice

### Product Card Description

```tsx
<ExpandableText
  text={product.description}
  maxLines={2}
  showText="View full description"
  hideText="Show less"
  className="product-card__description"
/>
```

### Mobile-Only Truncation

```tsx
<ExpandableText
  text={article.content}
  maxLines={4}
  breakpoint="md"
  showText="Continue reading"
  hideText="Show summary"
/>
```

### With Custom Styling

```tsx
<ExpandableText
  text={review.text}
  maxLines={3}
  textProps={{
    variant: "small",
    className: "review-text"
  }}
  accordionProps={{
    headerPosition: "top"
  }}
/>
```
