# Keyboard Support - Test Instructions

## ⚠️ Breaking Change

**Version 2.0** uses HTMX configuration objects instead of simple URL strings. The old format is **not supported**.

**Old format (no longer supported)**:
```javascript
{"A": "/url"}
```

**New format (required)**:
```javascript
{"A": {"hx-post": "/url"}}
```

## Files

- `keyboard_support.js` - Main keyboard support library with smart timeout logic
- `test_keyboard_support.html` - Test page to verify functionality

## Key Features

### Scope Control with `require_inside`

Each combination can declare whether it should only trigger when the focus is **inside** the registered element, or fire **globally** regardless of focus.

| `require_inside` | Behavior |
|-----------------|----------|
| `true` (default) | Triggers only if focus is inside the element or one of its children |
| `false` | Triggers regardless of where the focus is (global shortcut) |

```javascript
// Only fires when focus is inside #tree-panel
add_keyboard_support('tree-panel', '{"esc": {"hx-post": "/cancel", "require_inside": true}}');

// Fires anywhere on the page
add_keyboard_support('app', '{"ctrl+n": {"hx-post": "/new", "require_inside": false}}');
```

**Python usage (`Keyboard` component):**

```python
# Default: require_inside=True — fires only when inside the element
Keyboard(self, _id="-kb").add("esc", self.commands.cancel())

# Explicit global shortcut
Keyboard(self, _id="-kb").add("ctrl+n", self.commands.new_item(), require_inside=False)
```

### Multiple Simultaneous Triggers

**IMPORTANT**: If multiple elements listen to the same combination, all of them whose `require_inside` condition is satisfied will be triggered simultaneously:

```javascript
add_keyboard_support('modal',   '{"esc": {"hx-post": "/close-modal",  "require_inside": true}}');
add_keyboard_support('editor',  '{"esc": {"hx-post": "/cancel-edit",  "require_inside": true}}');
add_keyboard_support('sidebar', '{"esc": {"hx-post": "/hide-sidebar", "require_inside": false}}');

// Pressing ESC while focus is inside 'editor':
//   - 'modal'   → skipped (require_inside: true, focus not inside)
//   - 'editor'  → triggered ✓
//   - 'sidebar' → triggered ✓ (require_inside: false)
```

### Smart Timeout Logic (Longest Match)

The library uses **a single global timeout** based on the sequence state, not on individual elements:

**Key principle**: If **any element** has a longer sequence possible, **all matching elements wait**.

Examples:

**Example 1**: Three elements, same combination
```javascript
add_keyboard_support('elem1', '{"esc": "/url1"}');
add_keyboard_support('elem2', '{"esc": "/url2"}');
add_keyboard_support('elem3', '{"esc": "/url3"}');
// Press ESC → ALL 3 trigger immediately (no longer sequences exist)
```

**Example 2**: Mixed - one has longer sequence
```javascript
add_keyboard_support('elem1', '{"A": "/url1"}');
add_keyboard_support('elem2', '{"A": "/url2"}');
add_keyboard_support('elem3', '{"A": "/url3", "A B": "/url3b"}');
// Press A:
// - elem3 has "A B" possible → EVERYONE WAITS 500ms
// - If B arrives: only elem3 triggers with "A B"
// - If timeout expires: elem1, elem2, elem3 ALL trigger with "A"
```

**Example 3**: Different combinations
```javascript
add_keyboard_support('elem1', '{"A B": "/url1"}');
add_keyboard_support('elem2', '{"C D": "/url2"}');
// Press A: elem1 waits for B, elem2 not affected
// Press C: elem2 waits for D, elem1 not affected
```

The timeout is tied to the **sequence being typed**, not to individual elements.

### Enabling and Disabling Combinations

Each combination can be enabled or disabled independently. A disabled combination is registered and tracked, but its action is never triggered.

| State | Behavior |
|-------|----------|
| `enabled=True` (default) | Combination triggers normally |
| `enabled=False` | Combination is silently ignored when pressed |

**Setting the initial state at registration:**

```python
# Enabled by default
keyboard.add("ctrl+s", self.commands.save())

# Disabled at startup
keyboard.add("ctrl+d", self.commands.delete(), enabled=False)
```

**Toggling dynamically at runtime:**

Use `mk_enable()` and `mk_disable()` to change the state from a server response. Both methods return an out-of-band HTMX element (`hx-swap-oob`) that updates the DOM without a full page reload.

```python
# Enable a combination (e.g., once an item is selected)
def handle_select(self):
    item = ...
    return item.render(), self.keyboard.mk_enable("ctrl+d")

# Disable a combination (e.g., when nothing is selected)
def handle_deselect(self):
    return self.keyboard.mk_disable("ctrl+d")
```

The enabled state is stored in a hidden control `<div>` rendered alongside the keyboard script. The JavaScript reads this state before triggering any action.

**State at a glance:**

```
┌─────────────────────────────────────┐
│  Keyboard control div (hidden)      │
│  ┌──────────────────────────────┐   │
│  │ div [data-combination="esc"] │   │
│  │     [data-enabled="true"]    │   │
│  ├──────────────────────────────┤   │
│  │ div [data-combination="ctrl+d"] │ │
│  │     [data-enabled="false"]   │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
```

### Smart Timeout Logic (Longest Match)

Keyboard shortcuts are **disabled** when typing in input fields:
- `<input>` elements
- `<textarea>` elements  
- Any `contenteditable` element

This ensures normal typing (Ctrl+C, Ctrl+A, etc.) works as expected in forms.

## How to Test

1. **Download both files** to the same directory
2. **Open `test_keyboard_support.html`** in a web browser
3. **Try the configured shortcuts**:
   - `a` - Simple key (waits if "A B" might follow)
   - `Ctrl+S` - Save combination (immediate)
   - `Ctrl+C` - Copy combination (waits because "Ctrl+C C" exists)
   - `A B` - Sequence (waits because "A B C" exists)
   - `A B C` - Triple sequence (triggers immediately)
   - `Ctrl+C C` - Press Ctrl+C together, release, then press C alone
   - `Ctrl+C Ctrl+C` - Press Ctrl+C, keep Ctrl, release C, press C again
   - `shift shift` - Press Shift twice in sequence
   - `esc` - Escape key (immediate)

4. **Test focus behavior**:
   - Click on the test element to focus it (turns blue)
   - Try shortcuts with focus
   - Click outside to remove focus
   - Try shortcuts without focus
   - The log shows whether the element had focus when triggered

5. **Test input protection**:
   - Try typing in the input field
   - Use Ctrl+C, Ctrl+A, etc. - should work normally
   - Shortcuts should NOT trigger while typing in input

## Expected Behavior

### Smart Timeout Examples

**Scenario 1**: Only "A" is configured (no element has "A B")
- Press A → Triggers **immediately**

**Scenario 2**: At least one element has "A B"
- Press A → **ALL elements with "A" wait 500ms**
- If B pressed within 500ms → Only elements with "A B" trigger
- If timeout expires → ALL elements with "A" trigger

**Scenario 3**: "A", "A B", and "A B C" all configured (same or different elements)
- Press A → Waits (because "A B" exists)
- Press B → Waits (because "A B C" exists)
- Press C → Triggers "A B C" **immediately**

**Scenario 4**: Multiple elements, ESC on all
```javascript
add_keyboard_support('modal', '{"esc": "/close"}');
add_keyboard_support('editor', '{"esc": "/cancel"}');
```
- Press ESC → **Both trigger simultaneously** (no longer sequences)

## Integration in Your Project

## Integration in Your Project

### Configuration Format

The library now uses **HTMX configuration objects** instead of simple URL strings:

```python
# New format with HTMX configuration
combinations = {
    "Ctrl+S": {
        "hx-post": "/save-url",
        "hx-target": "#result",
        "hx-swap": "innerHTML"
    },
    "A B": {
        "hx-post": "/sequence-url",
        "hx-vals": {"extra": "data"}
    },
    "esc": {
        "hx-get": "/cancel-url"
    }
}

# This will generate the JavaScript call
f"add_keyboard_support('{element_id}', '{json.dumps(combinations)}')"
```

### Supported HTMX Attributes

You can use any HTMX attribute in the configuration object:

**HTTP Methods** (one required):
- `hx-post` - POST request
- `hx-get` - GET request
- `hx-put` - PUT request
- `hx-delete` - DELETE request
- `hx-patch` - PATCH request

**Common Options**:
- `hx-target` - Target element selector
- `hx-swap` - Swap strategy (innerHTML, outerHTML, etc.)
- `hx-vals` - Additional values to send (object)
- `hx-vals-extra` - Extra values to merge (see below)
- `hx-headers` - Custom headers (object)
- `hx-select` - Select specific content from response
- `hx-confirm` - Confirmation message

All other `hx-*` attributes are supported and will be converted to the appropriate htmx.ajax() parameters.

### Dynamic Values with hx-vals-extra

The `hx-vals-extra` attribute allows adding dynamic values computed at event time, without overwriting the static `hx-vals`.

**Format:**
```javascript
{
  "hx-vals": {"c_id": "command_id"},           // Static values (preserved)
  "hx-vals-extra": {
    "dict": {"key": "value"},                  // Additional static values (merged)
    "js": "functionName"                       // JS function to call (merged)
  }
}
```

**How values are merged:**
1. `hx-vals` - static values (e.g., `c_id` from Command)
2. `hx-vals-extra.dict` - additional static values
3. `hx-vals-extra.js` - function called with `(event, element, combinationStr)`, result merged

**JavaScript function example:**
```javascript
function getKeyboardContext(event, element, combination) {
  return {
    key: event.key,
    shift: event.shiftKey,
    timestamp: Date.now()
  };
}
```

**Configuration example:**
```javascript
const combinations = {
  "Ctrl+S": {
    "hx-post": "/save",
    "hx-vals": {"c_id": "save_cmd"},
    "hx-vals-extra": {"js": "getKeyboardContext"}
  }
};
```

### Automatic Parameters

The library automatically adds these parameters to every request:
- `combination` - The combination that triggered the action (e.g., "Ctrl+S")
- `has_focus` - Boolean indicating if the element had focus
- `is_inside` - Boolean indicating if the focus is inside the element (element itself or any child)

Note: `require_inside` controls **whether** the action fires; `is_inside` is an informational parameter sent **with** the request after it fires.

Example final request:
```javascript
htmx.ajax('POST', '/save-url', {
  target: '#result',
  swap: 'innerHTML',
  values: {
    extra: "data",           // from hx-vals
    combination: "Ctrl+S",   // automatic
    has_focus: true,         // automatic
    is_inside: true          // automatic
  }
})
```

## Integration Examples

### Basic Usage

```python
combinations = {
    "Ctrl+S": {
        "hx-post": "/save"
    }
}
```

### With Target and Swap

```python
combinations = {
    "Ctrl+D": {
        "hx-delete": "/item",
        "hx-target": "#item-list",
        "hx-swap": "outerHTML"
    }
}
```

### With Extra Values

```python
combinations = {
    "Ctrl+N": {
        "hx-post": "/create",
        "hx-vals": json.dumps({"type": "quick", "mode": "keyboard"})
    }
}
```

### Multiple Elements Example

```python
# Modal close
modal_combinations = {
    "esc": {
        "hx-post": "/modal/close",
        "hx-target": "#modal",
        "hx-swap": "outerHTML"
    }
}

# Editor cancel
editor_combinations = {
    "esc": {
        "hx-post": "/editor/cancel",
        "hx-target": "#editor",
        "hx-swap": "innerHTML"
    }
}

# Both will trigger when ESC is pressed
f"add_keyboard_support('modal', '{json.dumps(modal_combinations)}')"
f"add_keyboard_support('editor', '{json.dumps(editor_combinations)}')"
```

### Removing Keyboard Support

When you no longer need keyboard support for an element:

```python
# Remove keyboard support
f"remove_keyboard_support('{element_id}')"
```

**Behavior**:
- Removes the element from the keyboard registry
- If this was the last element, automatically detaches global event listeners
- Cleans up all associated state (timeouts, snapshots, etc.)
- Other elements continue to work normally

**Example**:
```javascript
// Add support
add_keyboard_support('modal', '{"esc": {"hx-post": "/close"}}');

// Later, remove support
remove_keyboard_support('modal');
// If no other elements remain, keyboard listeners are completely removed
```

## API Reference

### add_keyboard_support(elementId, controlDivId, combinationsJson)

Adds keyboard support to an element.

**Parameters**:
- `elementId` (string): ID of the HTML element to watch for key events
- `controlDivId` (string): ID of the keyboard control div rendered by `Keyboard.render()`, used to look up enabled/disabled state at runtime
- `combinationsJson` (string): JSON string of combinations with HTMX configs

**Returns**: void

### Python Component Methods

These methods are available on the `Keyboard` instance.

#### add(sequence, command, require_inside=True, enabled=True)

Registers a key combination.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `sequence` | `str` | Key combination string, e.g. `"ctrl+s"`, `"esc"`, `"a b"` | — |
| `command` | `Command` | Command to execute when the combination is triggered | — |
| `require_inside` | `bool` | If `True`, only triggers when focus is inside the element | `True` |
| `enabled` | `bool` | Whether the combination is active at render time | `True` |

**Returns**: `self` (chainable)

#### mk_enable(sequence)

Returns an out-of-band HTMX element that enables a combination at runtime.

| Parameter | Type | Description |
|-----------|------|-------------|
| `sequence` | `str` | Key combination to enable, must match exactly what was passed to `add()` |

**Returns**: `Div` with `hx-swap-oob="true"`

#### mk_disable(sequence)

Returns an out-of-band HTMX element that disables a combination at runtime.

| Parameter | Type | Description |
|-----------|------|-------------|
| `sequence` | `str` | Key combination to disable, must match exactly what was passed to `add()` |

**Returns**: `Div` with `hx-swap-oob="true"`

---

### remove_keyboard_support(elementId)

Removes keyboard support from an element.

**Parameters**:
- `elementId` (string): ID of the HTML element

**Returns**: void

**Side effects**:
- If last element: detaches global event listeners and cleans up all state

## Technical Details

### Trie-based Matching

The library uses a prefix tree (trie) data structure:
- Each node represents a keyboard snapshot (set of pressed keys)
- Leaf nodes contain the HTMX configuration object
- Intermediate nodes indicate longer sequences exist
- Enables efficient O(n) matching where n is sequence length

### HTMX Integration

Configuration objects are mapped to htmx.ajax() calls:
- `hx-*` attributes are converted to camelCase parameters
- HTTP method is extracted from `hx-post`, `hx-get`, etc.
- `combination`, `has_focus`, and `is_inside` are automatically added to values
- All standard HTMX options are supported

### Key Normalization

- Case-insensitive: "ctrl" = "Ctrl" = "CTRL"
- Mapped keys: "Control" → "ctrl", "Escape" → "esc", "Delete" → "del"
- Simultaneous keys represented as sorted sets

## Notes

- The test page mocks `htmx.ajax` to display results in the console
- In production, real AJAX calls will be made to your backend
- Sequence timeout is 500ms between keys
- Maximum 10 snapshots kept in history to prevent memory issues