npm package: @oceanswave/solari-split-flap
Description: A realistic split-flap (Solari board) display component for React + TypeScript. Cycles through quotes with authentic mechanical flip animations and synthesised click sounds.
Author: Sean
Latest version: 1.0.2

# Solari Split-Flap Display

A realistic split-flap (Solari board) display for the web. Cycles through quotes with authentic mechanical flip animations and optional click sounds via the Web Audio API.

Inspired by the classic electromechanical displays found in airports and train stations worldwide.

![Solari Board](https://img.shields.io/badge/display-split--flap-yellow)
![License](https://img.shields.io/badge/license-MIT-blue)

## Features

- Authentic split-flap flip animation using CSS 3D transforms
- Character drum cycling — characters flip through the full alphabet like a real Solari board
- Mechanical click sound via Web Audio API (synthesized, no audio files needed)
- **Controlled mode** — drive the board from React state, animate on prop changes
- **Uncontrolled mode** — auto-cycle through a list of quotes
- **Imperative ref API** — `flipTo()` and `clear()` for programmatic control
- **`onAnimationComplete`** callback when all cells finish flipping
- **Custom drum characters** — define your own character set
- **Responsive scaling** — `scale` prop scales all dimensions proportionally
- Per-line colours — any row can have its own CSS colour
- `@` shorthand still works for gold author attributions
- Helper utilities for easy text input — just pass plain strings
- Fully tested with Vitest + React Testing Library
- Linted and formatted with [Biome](https://biomejs.dev/)
- Available as both a **standalone HTML** page and a **React + TypeScript** component

## Quick Start — Standalone HTML

Open `demo/index.html` in your browser. That's it — no build step, no dependencies.

## React Component

```bash
npm install @oceanswave/solari-split-flap
```

### Controlled mode — drive it from React state

Pass a single `value` and the board animates to it whenever it changes. No auto-cycling — you own the state.

```tsx
import { useState } from 'react';
import { SolariBoard, textToQuote } from '@oceanswave/solari-split-flap';

function App() {
  const [message, setMessage] = useState(textToQuote('Hello world', 20));

  return (
    <>
      <SolariBoard value={message} />
      <button onClick={() => setMessage(textToQuote('Goodbye world', 20))}>
        Change
      </button>
    </>
  );
}
```

### Uncontrolled mode — auto-cycle through quotes

```tsx
import { SolariBoard, parseQuotes } from '@oceanswave/solari-split-flap';

const quotes = parseQuotes([
  'The only limit is your imagination.',
  'Stay hungry. Stay foolish.',
  'Make it simple, but significant.',
]);

function App() {
  return <SolariBoard quotes={quotes} />;
}
```

### Imperative ref — programmatic control

```tsx
import { useRef } from 'react';
import { SolariBoard, textToQuote } from '@oceanswave/solari-split-flap';
import type { SolariBoardHandle } from '@oceanswave/solari-split-flap';

function App() {
  const boardRef = useRef<SolariBoardHandle>(null);

  return (
    <>
      <SolariBoard ref={boardRef} />
      <button onClick={() => boardRef.current?.flipTo(textToQuote('New message', 20))}>
        Flip
      </button>
      <button onClick={() => boardRef.current?.clear()}>
        Clear
      </button>
    </>
  );
}
```

### Animation complete callback

```tsx
<SolariBoard
  value={message}
  onAnimationComplete={() => console.log('All cells done flipping!')}
/>
```

### Responsive sizing

```tsx
<SolariBoard scale={0.5} />   {/* half size — great for mobile */}
<SolariBoard scale={2} />     {/* double size — for large displays */}
```

### Custom drum characters

```tsx
<SolariBoard drum=" 0123456789:.APM" />   {/* clock-style: digits, colon, AM/PM */}
```

### With authors (gold attribution)

```tsx
const quotes = parseQuotes([
  { text: 'The only thing we have to fear is fear itself.', author: 'FDR' },
  { text: 'I think, therefore I am.', author: 'Descartes' },
]);
```

### Custom colours per quote

```tsx
const quotes = parseQuotes([
  { text: 'System online.', color: '#4ade80' },
  { text: 'Warning: disk full.', color: '#f87171' },
  { text: 'Welcome aboard!', color: '#60a5fa', author: 'Captain' },
  { text: 'Danger!', color: '#ff4444', author: 'System', authorColor: '#aaaaaa' },
]);
```

### Per-line colour control

Each line in a quote can be a plain string or a `{ text, color? }` object — mix and match freely:

```tsx
const quotes = [
  [
    { text: 'RED ALERT', color: '#ff4444' },
    { text: 'ALL SYSTEMS', color: '#ffffff' },
    { text: 'NOMINAL', color: '#4ade80' },
  ],
  [
    'PLAIN WHITE LINE',
    { text: 'GOLD ACCENT', color: '#f5c542' },
    '@CLASSIC AUTHOR STYLE',       // still works — gold via @ prefix
  ],
];

<SolariBoard quotes={quotes} />
```

### Board-wide default colour

```tsx
<SolariBoard defaultColor="#60a5fa" />   {/* all text blue unless overridden */}
```

### Word-wrap a single string

```tsx
import { textToQuote } from '@oceanswave/solari-split-flap';

textToQuote('The quick brown fox jumps over the lazy dog.', 20)
textToQuote('Alert!', 20, { color: '#ff4444', author: 'System', authorColor: '#aaa' })
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Quote` | — | **Controlled mode.** Board animates to this value on change. When set, `quotes`/`holdMs` are ignored. |
| `quotes` | `Quote[]` | Built-in quotes | **Uncontrolled mode.** Array of quotes to auto-cycle through. Ignored when `value` is set. |
| `ref` | `Ref<SolariBoardHandle>` | — | Imperative handle with `flipTo(quote)` and `clear()` methods. |
| `cols` | number | `20` | Number of columns (characters per row) |
| `rows` | number | `8` | Number of rows |
| `defaultColor` | string | `'#f0f0f0'` | Default text colour for rows without an explicit colour |
| `scale` | number | `1` | Scale multiplier for cell dimensions. `0.5` = half size, `2` = double, etc. |
| `drum` | string | `' A-Z0-9.,…'` | Custom drum character sequence. Flaps cycle through this ordered string. |
| `holdMs` | number | `5000` | Milliseconds to hold each quote before clearing |
| `charDelay` | number | `50` | Stagger delay (ms) between cell animations |
| `flipMs` | number | `150` | Duration of a single flap flip |
| `minGap` | number | `35` | Fastest drum-step interval (ms) |
| `maxGap` | number | `160` | Slowest drum-step interval (ms) |
| `sound` | boolean | `true` | Enable/disable flip click sounds |
| `onAnimationComplete` | `() => void` | — | Fired when all cells finish flipping to their targets. |
| `className` | string | `''` | Additional CSS class for the board |
| `style` | object | `{}` | Additional inline styles for the board |

### Exports

```tsx
import { SolariBoard, textToQuote, parseQuotes } from '@oceanswave/solari-split-flap';
import type { SolariBoardProps, SolariBoardHandle, Quote, QuoteLine, TextToQuoteOptions } from '@oceanswave/solari-split-flap';
```

### Types

```tsx
type QuoteLine = string | { text: string; color?: string };
type Quote = QuoteLine[];

interface SolariBoardHandle {
  flipTo: (quote: Quote) => void;
  clear: () => void;
}

interface TextToQuoteOptions {
  author?: string;
  color?: string;         // body line colour
  authorColor?: string;   // author line colour (default: '#f5c542' gold)
}
```

## Development

```bash
npm install
npm run test          # Vitest
npm run test:watch    # Vitest in watch mode
npm run lint          # Biome check
npm run lint:fix      # Biome auto-fix
npm run format        # Biome format
npm run typecheck     # TypeScript --noEmit
npm run ci            # Biome ci + typecheck + tests
npm run build         # Compile to dist/
```

## How It Works

Each cell in the grid consists of four layers:

1. **Top flap** — shows the top half of the current character
2. **Bottom flap** — shows the bottom half of the new character (revealed as the top flap falls)
3. **Flip front** — animated element showing the old character's top half, rotates down
4. **Flip back** — backface of the flip, shows the new character's bottom half

The flip animation uses `rotateX(-180deg)` with `backface-visibility: hidden` and `transform-style: preserve-3d` for realistic 3D flipping.

Characters cycle through a **drum** (`SPACE → A-Z → 0-9 → punctuation`) to reach their target, just like a real mechanical display where each flap must pass through all intermediate characters.

Timing decelerates toward the target character (fast start, slow finish) for a natural mechanical feel.

## License

MIT