# Croupier API Reference

Complete reference for the Croupier public API.

## Croupier.create(container, config)

Creates a new swipe deck instance.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `container` | `string \| HTMLElement` | yes | CSS selector or DOM element |
| `config` | `object` | yes | Configuration object |

**Returns:** `CroupierDeck` instance

### Config

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `items` | `T[]` | `[]` | Array of items to display |
| `renderCard` | `(item, ctx) => string \| HTMLElement \| Promise` | — | Render function for each card |
| `actions` | `object` | `{ reject, accept, save }` | Action definitions |
| `hooks` | `object` | `{}` | Lifecycle hooks |
| `theme` | `object` | `{}` | CSS custom property overrides |
| `getLabel` | `(item, index, total) => string` | `"Card X of Y"` | Accessibility label per card |
| `stackSize` | `number` | `4` | Number of visible cards in the stack |
| `sensitivityPx` | `number` | `80` | Drag distance (px) to trigger an action |
| `maxHistory` | `number` | `50` | Maximum undo history entries |

### Actions

Each key in the `actions` object defines one action:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Displayed in badge and toast |
| `keys` | `string[]` | yes | Keyboard keys that trigger the action |
| `theme` | `'positive' \| 'negative' \| 'neutral' \| 'accent'` | yes | Color semantics |
| `symbol` | `string` | no | Icon shown on the action button (default: `✕`, `✓`, `★` for reject/accept/save, `•` for custom) |

**Default actions:**

```js
{
  reject: { label: 'Archive', keys: ['ArrowLeft'],  theme: 'negative' },
  accept: { label: 'Read',    keys: ['ArrowRight'], theme: 'positive' },
  save:   { label: 'Save',    keys: ['ArrowUp'],    theme: 'neutral' },
}
```

### Hooks

| Hook | Payload | Description |
|------|---------|-------------|
| `onAction` | `{ action, item, direction }` | Called when an action is executed |
| `onEmpty` | `{ stats }` | Called when the deck is empty |
| `onUndo` | `{ item, previousAction }` | Called when an action is undone |

## Deck methods

### `dispatch(actionName)`

Triggers an action programmatically.

| Param | Type | Description |
|-------|------|-------------|
| `actionName` | `string` | Key from the `actions` config |

### `undo()`

Undoes the last action. Cancels in-progress animations if needed.

### `reset()`

Resets the deck to its initial state (items, stats, history).

### `load(newItems)`

Replaces the deck's items and resets state.

| Param | Type | Description |
|-------|------|-------------|
| `newItems` | `T[]` | New array of items |

### `destroy()`

Removes all listeners, cancels animations, and clears the DOM.

### `on(event, handler, opts?)`

Subscribes to a deck event.

| Param | Type | Description |
|-------|------|-------------|
| `event` | `string` | Event name (see Events) |
| `handler` | `function` | Callback function |
| `opts.await` | `boolean` | If true, handler is awaited (with 250ms timeout) |

### `off(event, handler)`

Unsubscribes from a deck event.

## Events

| Event | Value | Payload | Description |
|-------|-------|---------|-------------|
| `ACTION` | `cr:action` | `{ action, item, direction }` | Action executed |
| `UNDO` | `cr:undo` | `{ item, previousAction }` | Action undone |
| `ADVANCE` | `cr:advance` | `{ discarded, remaining }` | Deck advanced |
| `EMPTY` | `cr:empty` | `{ stats }` | Deck is empty |
| `FOCUS` | `cr:focus` | `{ item, index, element }` | Card became top |
| `BLUR` | `cr:blur` | `{ item, index, element }` | Card left top |
| `DESTROY` | `cr:destroy` | `{}` | Deck destroyed |

Access via `Croupier.Events`:

```js
import { Croupier } from 'croupier';
deck.on(Croupier.Events.ACTION, ({ action, item }) => { ... });
```

## Deck properties (readonly)

| Property | Type | Description |
|----------|------|-------------|
| `items` | `T[]` | Current items |
| `index` | `number` | Current index |
| `stats` | `object` | `{ actionName: count }` |
| `actions` | `object` | Action configurations |

## CSS custom properties

### Surface

| Property | Default | Description |
|----------|---------|-------------|
| `--cr-bg-base` | `#F4ECD9` | Page background |
| `--cr-bg-surface` | `#FBF6EA` | Card background |
| `--cr-bg-elevated` | `#FFFBF0` | Elevated surfaces |
| `--cr-bg-overlay` | `rgba(33,25,19,0.45)` | Overlay |

### Border

| Property | Default | Description |
|----------|---------|-------------|
| `--cr-border-subtle` | `color-mix(...)` | Subtle border |
| `--cr-border-strong` | `color-mix(...)` | Strong border |

### Text

| Property | Default | Description |
|----------|---------|-------------|
| `--cr-text-primary` | `#211913` | Primary text |
| `--cr-text-secondary` | `#6B5D4F` | Secondary text |
| `--cr-text-tertiary` | `#7A6C5E` | Tertiary text |
| `--cr-text-quaternary` | `#9A8E80` | Quaternary text |

### Accent

| Property | Default | Description |
|----------|---------|-------------|
| `--cr-accent` | `#E8553A` | Accent color |
| `--cr-accent-soft` | `#F0846E` | Soft accent |

### Actions

| Property | Default | Description |
|----------|---------|-------------|
| `--cr-action-reject` | `#9E3E2B` | Reject action color |
| `--cr-action-accept` | `#16786E` | Accept action color |
| `--cr-action-save` | `#E8A33D` | Save action color |
| `--cr-action-undo` | `#8D4A64` | Undo action color |

### Depth (registered via @property)

| Property | Syntax | Initial | Description |
|----------|--------|---------|-------------|
| `--cr-depth-scale` | `<number>` | `1` | Card scale at current depth |
| `--cr-depth-y` | `<length>` | `0px` | Card Y offset at current depth |
| `--cr-depth-opacity` | `<number>` | `1` | Card opacity at current depth |

## CSS classes

| Class | Element | Description |
|-------|---------|-------------|
| `.cr-card` | `article` | Individual card |
| `.cr-stack` | `div` | Card stack container |
| `.cr-header` | `div` | Header bar |
| `.cr-main` | `div` | Main content area |
| `.cr-actions` | `div` | Action buttons container |
| `.cr-action-btn` | `button` | Individual action button |
| `.cr-toast` | `div` | Center toast |
| `.cr-stats-bar` | `div` | Stats bar |
| `.cr-empty` | `div` | Empty state |
| `.cr-kbd-hint` | `div` | Keyboard hints |
| `.cr-badge` | `div` | Action badge on card |
| `.cr-counter` | `div` | Position counter |
| `.cr-sr-only` | `div` | Screen reader only |