npm package: @mkteagle/components
Description: A modern React component library featuring lyric generation, aurora animations, and more
Author: mkteagle
Latest version: 2.9.0

# Lyric Ipsum Widget

A modern, streamlined React component for generating and displaying song lyrics with aurora borealis loading animations.

## Theming

You can fully customize the look and feel of the components using the `ThemeProvider` and its `theme` prop. The theme is applied via CSS custom properties, allowing for easy runtime switching and deep customization. All major UI colors and states are themeable.

### Example

```tsx
import { ThemeProvider } from "@mkteagle/components";

const theme = {
  inputBackground: "#fff",
  labelColor: "#374151",
  helperTextColor: "#6b7280",
  placeholderColor: "#9ca3af",
  buttonBackground: "#0891b2",
  buttonForeground: "#fff",
  checkboxBackground: "#fff",
  checkboxBorder: "#0891b2",
  selectBackground: "#fff",
  selectBorder: "#0891b2",
  focusRing: "#38bdf8",
};

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>;
```

### Theme Properties

- `inputBackground`: Background color for input fields
- `labelColor`: Color for all form labels and key UI text
- `helperTextColor`: Color for helper/instructional text and secondary info
- `placeholderColor`: Color for input and select placeholders
- `buttonBackground`: Background color for buttons
- `buttonForeground`: Text color for buttons
- `checkboxBackground`: Background color for checkboxes
- `checkboxBorder`: Border color for checkboxes
- `selectBackground`: Background color for select dropdowns
- `selectBorder`: Border color for select dropdowns
- `focusRing`: Color for focus ring outlines on interactive elements

All properties are optional; defaults are provided for accessibility and visual clarity. You can override any subset to match your brand or application's theme.
return (
<div>
<LyricIpsum
apiUrl="https://lyrics.mkteagle.com/api/random-lyrics"
theme="auto"
onLyricsLoad={(data) => console.log("Lyrics loaded:", data)}
onError={(error) => console.error("Error:", error)}
/>
</div>
);
}

````

## Props

| Prop                | Type                          | Default                                           | Description                           |
| ------------------- | ----------------------------- | ------------------------------------------------- | ------------------------------------- |
| `apiUrl`            | `string`                      | `"https://lyrics.mkteagle.com/api/random-lyrics"` | API endpoint URL for fetching lyrics  |
| `className`         | `string`                      | `""`                                              | Custom CSS class name for styling     |
| `style`             | `React.CSSProperties`         | `undefined`                                       | Custom inline styles                  |
| `onLyricsLoad`      | `(data: LyricData) => void`   | `undefined`                                       | Callback fired when lyrics are loaded |
| `onError`           | `(error: string) => void`     | `undefined`                                       | Callback fired when an error occurs   |
| `showFilters`       | `boolean`                     | `true`                                            | Whether to show search controls       |
| `searchPlaceholder` | `string`                      | `"Search artist - song or keywords..."`           | Placeholder text for search input     |
| `theme`             | `"light" \| "dark" \| "auto"` | `"auto"`                                          | Theme variant                         |
| `demoMode`          | `boolean`                     | `false`                                           | Use demo mode with mock data          |

## CORS Handling

The component automatically handles CORS issues when making requests to external APIs:

1. **Direct API Call**: First attempts a direct fetch to your API endpoint
2. **CORS Proxy Fallback**: If CORS blocks the request, automatically falls back to using `https://api.allorigins.win` as a proxy
3. **Demo Mode**: Set `demoMode={true}` to use mock data for testing when the API is unavailable

```tsx
// For development/testing with mock data
<LyricIpsum demoMode={true} />

// For production with automatic CORS handling
<LyricIpsum apiUrl="https://your-api.com/lyrics" />
````

## API Endpoint Requirements

Your API endpoint should:

1. Accept GET requests with optional query parameters:

   - `search`: Search query string
   - `passages`: Number of passages to return
   - `plain`: Boolean flag for plain text format

2. Return JSON in this format:
   ```json
   {
     "title": "Song Title",
     "artist": "Artist Name",
     "url": "https://genius.com/song-url",
     "lyrics": "Song lyrics...",
     "description": "Song description",
     "album": "Album Name",
     "release_date": "2023-01-01",
     "lyrics_state": "complete",
     "annotation_count": 42
   }
   ```

## Components

### LyricIpsum (Main Component)

The main component that combines all features.

### AuroraLoader

Aurora borealis loading animation component.

### FilterControls

Inline search and filter controls.

### LyricsDisplay

Formatted lyrics display with metadata.

## Styling

The component comes with default styles, but you can customize it:

```css
.lyric-ipsum {
  /* Custom container styles */
}

.lyric-ipsum--dark {
  /* Dark theme customizations */
}

.aurora-loader {
  /* Custom loading animation styles */
}
```

## TypeScript

Full TypeScript support is included:

```tsx
import { LyricIpsum, LyricData, LyricIpsumProps } from "lyric-ipsum-widget";

const handleLyricsLoad = (data: LyricData) => {
  console.log(`Loaded "${data.title}" by ${data.artist}`);
};

const MyComponent: React.FC = () => (
  <LyricIpsum onLyricsLoad={handleLyricsLoad} theme="dark" />
);
```

## License

MIT © mkteagle