@leverj/flipcard NPM

Flipcard

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.

Features

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

Installation

npm install @leverj/flipcard
# or
yarn add @leverj/flipcard

Import Options

The component can be imported in several ways depending on your use case:

Option 1: Custom Element Usage (Recommended for most cases)

// This will register the custom element automatically
import '@leverj/flipcard';

// Use in HTML or templates
// <flipcard-viewer metadata-json="..." gateway-url="..."></flipcard-viewer>

Option 2: Class Import (For advanced use cases)

// 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();

Option 3: Default Import

// 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.

Usage

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>

Complete Example

<!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>

Properties

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`

Metadata JSON Format

{
  "image": "ipfs://QmHash...",
  "properties": {
    "display": {
      "rows": 2,
      "columns": 2
    }
  }
}

Development

# Install dependencies
yarn install

# Start development server
yarn dev

# Run tests
yarn test

# Build for production
yarn build

Debugging and Logging

The 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

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Safari iOS (13.4+)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Lit
EXIF data parsing with exifr

dekart flipcard lit-element web-components custom-elements

8 months ago

8 months ago

9 months ago

9 months ago