https://github.com/drbiznes/zaamurets
Zaamurets is a React component library for creating ASCII art trains with support for shields.io badges and custom content.
https://github.com/drbiznes/zaamurets
ascii ascii-art component component-library react readme readme-profile shieldsio trains typescript
Last synced: 8 months ago
JSON representation
Zaamurets is a React component library for creating ASCII art trains with support for shields.io badges and custom content.
- Host: GitHub
- URL: https://github.com/drbiznes/zaamurets
- Owner: DrBiznes
- License: mit
- Created: 2025-01-18T12:08:17.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-01-19T13:44:30.000Z (9 months ago)
- Last Synced: 2025-02-19T09:47:11.465Z (8 months ago)
- Topics: ascii, ascii-art, component, component-library, react, readme, readme-profile, shieldsio, trains, typescript
- Language: TypeScript
- Homepage: http://zaamurets.jamino.me/
- Size: 785 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Zaamurets
A React component library for creating ASCII art trains with support for shields.io badges and custom content. Create animated armored trains with shields.io badges for use in your projects. I use react-fast-marquee to animate it but do whatever floats your train. Visit the website for documentation and a train creator.
[Live Demo, Documentation, and Train Creator](https://zaamurets.jamino.me)
## Installation
```bash
npm install zaamurets
```
## Quick Start
```jsx
import { Train, TrainCar } from 'zaamurets';
import Marquee from 'react-fast-marquee';
// With scrolling animation
function Example() {
return (
);
}
// With track animation
function AnotherExample() {
return (
);
}
```
## Features
- ASCII art trains with engine, cars, and caboose
- Native support for shields.io badges
- Animated track effects (alternating track pattern)
- Clickable train cars with custom content
- TypeScript support
- Zero dependencies other than React
## Documentation
### Train Component
Main container component for creating an ASCII train.
#### Props
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | `undefined` | TrainCar components to be rendered |
| `additionalTrackSegments` | `number` | `0` | Add extra track segments after the train |
| `animated` | `boolean` | `false` | Enable track pattern animation (alternates between `-+-` and `+-+` patterns) |
### TrainCar Component
Individual car components that make up the train.
#### Props
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode \| BadgeConfig[]` | `undefined` | Content to display in the car |
| `href` | `string` | `undefined` | Makes the entire car clickable with this URL |
### Types
```typescript
interface BadgeConfig {
src: string; // URL of the badge image
href?: string; // Optional click URL for the badge
alt?: string; // Optional alt text for the badge
}
```
## Usage Examples
### Basic Badge Display
```jsx
import { Train, TrainCar } from 'zaamurets';
function BasicExample() {
return (
);
}
```
### Multiple Badges in One Car
```jsx
import { Train, TrainCar } from 'zaamurets';
function MultiBadgeExample() {
const badges = [
{
src: "https://img.shields.io/badge/tests-passing-green",
href: "https://example.com/tests",
alt: "Tests Status"
},
{
src: "https://img.shields.io/badge/coverage-98%25-brightgreen",
href: "https://example.com/coverage",
alt: "Coverage Status"
}
];
return (
{badges}
);
}
```
### Animated Track Example
```jsx
import { Train, TrainCar } from 'zaamurets';
function AnimatedTrackExample() {
return (
);
}
```
### Clickable Car with Custom Content
```jsx
import { Train, TrainCar } from 'zaamurets';
function ClickableExample() {
return (
Star on GitHub
);
}
```
## API Guidelines
### Badge Limitations
Each train car is limited to a maximum of 2 badges to ensure proper display and readability.
### Performance Considerations
- The `animated` prop creates an interval timer to animate the track pattern. Use it sparingly in performance-critical applications
- Consider the total number of cars when implementing in production
- Ensure custom content is sized appropriately for car dimensions
## Browser Support
- Modern evergreen browsers (Chrome, Firefox, Safari, Edge)
- Internet Explorer is not supported
## Development
### Building
```bash
npm run build
```
### Testing
```bash
npm run test
```
### Linting
```bash
npm run lint
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT © [Jamino](https://github.com/DrBiznes)
## Related Projects
- [react-fast-marquee](https://www.npmjs.com/package/react-fast-marquee) - For animated train movement
- [shields.io](https://shields.io/) - For generating badges
## Support
For support, issues, or feature requests, please file an issue in the [GitHub repository](https://github.com/DrBiznes/zaamurets/issues).