# Bone Flow #120 Trigger

## Overview
#120 Trigger decides **what event starts Motion**. #119 State owns the current state, #118 Transition owns state transitions, #121 Timeline owns timing/order, and #122 KeyFrame owns intermediate values. Trigger does not take those responsibilities.

## Trigger responsibility
A Trigger listens to one formal event source and fires its callback once when the event condition is met. It reports Motion Start but does not implement animation timing or state interpolation.

## 10 formal Triggers
- Mouse Enter: `mouse-enter`.
- Mouse Leave: `mouse-leave`.
- Click: `click`.
- Double Click: `double-click`.
- Focus: `focus`.
- Blur: `blur`.
- Change: `change`.
- Parent Event: `parent-event`.
- Runtime Event: `runtime-event` with `BoneTrigger.emitRuntimeEvent()`.
- Command: `command` with `BoneTrigger.executeCommand()`.

## Operation
Use the permanent four-column interaction table on the test page. A Trigger passes only when the actual BoneTrigger callback is reached and Last Trigger / Motion Start are updated.

## Property
`type` accepts exactly the ten formal types. `enabled` defaults to true. Runtime Event requires `eventName`; Command requires `commandId`. `signalType` optionally rejects logical payloads whose signal type does not match.

## Preview
Apply Property settings to a real BoneTrigger instance attached to Preview Source. The preview updates only from the callback.

## Connection Image
The page uses #002 Bone Joint v1.1.36 APIs. Lines are generated by `BoneJoint.drawLine()`. Errors and compatibility markers use `BoneJoint.drawError()` / `BoneJoint.drawCompatibilityMarker()`. No private SVG path or fake Joint marker is used.

## Security
Payloads remain data. BoneTrigger does not evaluate strings or insert them as executable HTML. The Untrusted IN test sends an HTML-like string through Runtime Event and verifies that it stays data.

## OUT WAIT / FIFO / BLOCKED — formal #002 Delivery Channel
The panel follows the same presentation order as formal #017: title, responsibility note, one Source→Target stage, four status cells (Joint State / Target / Queue / Delivered), three actions, target receive log, and two visual confirmations. No two-column layout, side log panel, Target-state selector, payload selector, or separate FIFO button is used.

WAIT / FIFO: one “WAIT / FIFO” action creates the real #002 Delivery Channel with Target BUSY and fires two real #120 Click Trigger callbacks into Queue=2 / WAITING. The WAITING state remains visibly rendered for three seconds, matching the formal #002 “Target Busy 3-second visual test”. The same action then calls `setTargetReady(true)` on the #002 Delivery Channel, which automatically flushes `Trigger #1 → Trigger #2` in FIFO order and returns to READY. No separate Target READY button, FIFO button, Target-state selector, or payload selector is added.

BLOCKED: “BLOCKED” fires a real #120 callback through the #002 guard. Delivery is stopped while the connection remains established and the official BLOCKED marker is shown on the foreground overlay. “Reset” returns the channel to READY.

## Smoke / Validation
Smoke executes Runtime identity, all ten real callbacks, Functional Class mounting, #002 relation drawing, and #002 WAIT/BLOCKED. Validation covers invalid types, disabled triggers, signal mismatches, DOM spoof prevention, detach/reattach/destroy, untrusted payloads, Joint APIs, Guide route, and Functional Class contract.

## Completion
Complete is enabled only after **all Smoke/Validation checks pass and all nine required visual confirmations are checked**: ten real Trigger interactions, Property, Preview, #002 Connection Image, Security, #002 WAIT/BLOCKED, Guide JP/EN, Smoke, and Validation. Visual confirmation does not replace automated QA. The page supports Complete → Release Ready and Reopen → Development, but the package is not considered Completed / Specification Frozen before user localhost confirmation.

## HTML Functional Class {#bone-doc-section-html-functional-class}
The single normal-use class is `bf-trigger`. It owns only Trigger event wiring; it does not own target appearance, Transition, State, Timeline, or KeyFrame behavior.

Load order:
```html
<script src="/boneflow/js/bone-trigger.js"></script>
<script src="/boneflow/js/bone-trigger-functional-class.js"></script>
```

Attributes:
- `class="bf-trigger"`: required formal class.
- `data-trigger`: required, one of the ten Runtime types.
- `data-enabled`: optional `true` / `false`, default true.
- `data-event-name`: used by Runtime Event.
- `data-command-id`: used by Command.
- `data-signal-type`: optional payload type constraint.

Trigger mapping uses exactly: `mouse-enter`, `mouse-leave`, `click`, `double-click`, `focus`, `blur`, `change`, `parent-event`, `runtime-event`, `command`. Runtime Event also uses `data-event-name`; Command also uses `data-command-id`.

Minimal DOM Trigger:
```html
<button class="bf-trigger" data-trigger="click">Run</button>
```
The bridge auto-mounts the Runtime and emits `bone-trigger:fire` from the anchor when the callback is reached.

Parent Event uses the real parent CustomEvent path:
```html
<div id="parent"><button class="bf-trigger" data-trigger="parent-event">Child</button></div>
<script>
const child = document.querySelector('.bf-trigger[data-trigger="parent-event"]');
BoneTrigger.dispatchParentEvent(child.parentElement, { source: 'parent' });
</script>
```

Runtime Event:
```html
<div class="bf-trigger" data-trigger="runtime-event" data-event-name="order.updated"></div>
```
Command:
```html
<div class="bf-trigger" data-trigger="command" data-command-id="save"></div>
```
The anchor emits `bone-trigger:fire` when its callback is reached:
```html
<script>
document.querySelector('.bf-trigger').addEventListener('bone-trigger:fire', (event) => {
  console.log(event.detail.type, event.detail.motionStart);
});
</script>
```

Use `BoneTriggerHTMLClass.getInstance(element)` to obtain the mounted Runtime instance.

## Public API
Public Object: `BoneTrigger`. No public constructor class is exposed; it is a factory-style API.

- `create(options)`: create a Trigger instance.
- `attach(instance, target?)`: bind the instance to its formal event source.
- `detach(instance)`: stop listening without destroying it.
- `destroy(instance)`: detach and permanently invalidate the instance.
- `setEnabled(instance, enabled)`: enable/disable callback firing.
- `getState(instance)`: inspect type, enabled, attached, fire count and last trigger.
- `emitRuntimeEvent(eventName, payload)`: emit a named Runtime Event.
- `dispatchParentEvent(parent, payload)`: dispatch the formal parent CustomEvent.
- `executeCommand(commandId, payload)`: execute a named Command trigger.
- `list()`: inspect living Trigger instances.
- `isInstance(value)`: test Runtime instance identity.
- `validateOptions(options)`: validate the basic create contract without throwing.