A web component built with Lit for displaying interactive flipcard images with grid support. This package provides a custom element <flipcard-viewer> that can display and interact with grid-based flipcard images, supporting automatic orientation correction and responsive sizing.
- Grid-based image display with configurable rows and columns
- Interactive flip card animation
- Automatic image orientation correction (EXIF)
- Responsive sizing based on container dimensions
- IPFS gateway support
- Built with Lit for optimal performance
- Configurable logging system for debugging
- Thumbnail mode support
npm install @leverj/flipcard
# or
yarn add @leverj/flipcardThe component can be imported in several ways depending on your use case:
// This will register the custom element automatically
import '@leverj/flipcard';
// Use in HTML or templates
// <flipcard-viewer metadata-json="..." gateway-url="..."></flipcard-viewer>// Import the class directly
import { FlipcardViewer } from '@leverj/flipcard';
// The class can be used for:
// - Extending the component
// - Type checking
// - Programmatic element creation
const element = new FlipcardViewer();// Alternative way to import the class
import FlipCard from '@leverj/flipcard';Note: When using the component in frameworks like Vue, React, or Angular, you should use Option 1 (custom element usage) and ensure the component is properly registered in your framework's component system.
The component will be automatically registered as a custom element <flipcard-viewer>. You can use it directly in your HTML:
<flipcard-viewer
metadata-json='{
"image": "ipfs://QmExample...",
"properties": {
"display": {
"rows": 2,
"columns": 2
}
}
}'
gateway-url="https://www.ipfs.io/ipfs/"
is-thumbnail="true"
></flipcard-viewer><!DOCTYPE html>
<html>
<head>
<script type="module">
import '@leverj/flipcard';
</script>
</head>
<body>
<flipcard-viewer
metadata-json='{
"image": "ipfs://QmExample...",
"properties": {
"display": {
"rows": 2,
"columns": 2
}
}
}'
gateway-url="https://www.ipfs.io/ipfs/"
is-thumbnail="true"
></flipcard-viewer>
</body>
</html>| Property | Type | Description | Default |
|---|---|---|---|
metadata-json |
String | JSON string containing image metadata and display properties | "" |
gateway-url |
String | Base URL for the IPFS gateway | "https://www.ipfs.io/ipfs/" |
is-thumbnail |
Boolean | Whether to display in thumbnail mode (disables flip animation) | true |
{
"image": "ipfs://QmHash...",
"properties": {
"display": {
"rows": 2,
"columns": 2
}
}
}# Install dependencies
yarn install
# Start development server
yarn dev
# Run tests
yarn test
# Build for production
yarn buildThe component includes a configurable logging system that can be used to debug issues and monitor component behavior. You can configure logging in your application:
import { logger, LOG_LEVELS } from '@leverj/flipcard';
// Set log level (DEBUG, INFO, WARN, ERROR)
logger.setLogLevel('DEBUG');
// Enable/disable logging
logger.enableLogging();
logger.disableLogging();Available log levels:
-
DEBUG: Detailed debugging information -
INFO: General information about component operation -
WARN: Warning messages for potential issues -
ERROR: Error messages for critical issues
Example log output:
[Flipcard] Initializing FlipcardViewer
[Flipcard] Metadata parsed successfully { mediaUrl: "...", rows: 2, columns: 2 }
[Flipcard] Frame size calculated { frameWidth: 10, frameHeight: 10 }
[Flipcard] FlipcardViewer initialized successfully
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Safari iOS (13.4+)
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.