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

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 (

## 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:

   {
     "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:

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

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

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

TypeScript

Full TypeScript support is included:

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