# Bone Flow #118 Transition - HTML Functional Class Guide

Functional Class Version: 1.0.4  
Runtime: BoneTransition v1.0.3  
Normal-use HTML Functional Class: `bf-transition`

1. Introduction
#118 Transition owns one-time visual interpolation between semantic states. The Consumer owns the semantic state itself.
The single normal-use HTML Functional Class is `bf-transition`. The 21 Public API methods are not converted into 21 HTML classes.
This guide explains what HTML to write, which attributes are required, and how the Consumer invokes ENTER / EXIT on the mounted Runtime instance.

2. Responsibility boundary
- Consumer: owns semantic state such as open / closed / hidden / selected and decides when the target becomes displayable or hidden.
- #118: owns only ENTER / EXIT visual interpolation on the Target Part.
- #118 does not absorb #117 Animation, #116 Effect, State, Trigger, or Timeline responsibilities.
- The element carrying `bf-transition` is the real Transition Target Part. No duplicate visual target is created.

3. Load order
Load `BoneTransition v1.0.3` first, then `BoneTransitionFunctionalClass v1.0.4`.

```html
<script src="../js/bone-transition.js"></script>
<script src="../js/bone-transition-functional-class.js"></script>
```

Wrong order or a missing Runtime raises `TRANSITION_FUNCTIONAL_CLASS_RUNTIME_MISSING`.

4. Minimum HTML
The three relation attributes are required by the HTML Functional Class.

```html
<div
  class="bf-transition"
  data-transition-ui-no="UI-118-001"
  data-target-ui-no="UI-046-MENU"
  data-target-part="menu">
  Transition Target
</div>
```

The Functional Class creates one real `BoneTransition` instance and attaches it to that same host.

5. Configured HTML
```html
<div
  class="bf-transition"
  data-transition-ui-no="UI-118-MENU-001"
  data-target-ui-no="UI-046-MENU"
  data-target-part="menu"
  data-transition="slide-fade"
  data-direction="down"
  data-speed="fast"
  data-respect-reduced-motion="true">
  Menu content
</div>
```

6. HTML attributes
Required relation attributes:
- `data-transition-ui-no` -> transitionUiNo. #118 identifier. Required.
- `data-target-ui-no` -> targetUiNo. Consumer target UI identifier. Required.
- `data-target-part` -> targetPart. Consumer Target Part KEY. Required.

Transition options:
- `data-transition` -> transition. Default `fade`.
- `data-direction` -> direction. Default `down`; only used by transitions that consume Direction.
- `data-speed` -> speed. `slow / normal / fast`; default `normal`.
- `data-respect-reduced-motion` -> respectReducedMotion; default `true`.

Boolean forms: `true/false`, `1/0`, `yes/no`, `on/off`. Invalid values raise `TRANSITION_FUNCTIONAL_CLASS_BOOLEAN_INVALID`.

7. Runtime Default vs HTML Functional Class
BoneTransition Runtime defaults:
- transitionUiNo = UI-118-001
- targetUiNo = UI-046-MENU
- targetPart = menu
- transition = fade
- direction = down
- speed = normal
- respectReducedMotion = true

However, `bf-transition` requires the three relation attributes to be explicitly present in HTML. Do not omit them merely because Runtime defaults exist.

8. 23 Transitions
fade / slide / slide-fade / scale / scale-fade / zoom / zoom-fade / dissolve / wipe / reveal / expand / drop / pop / flip-x / flip-y / curtain-horizontal / curtain-vertical / shutter-horizontal / shutter-vertical / fold / rise / teleport-up / iris.
Direction is used by slide, slide-fade, wipe, reveal, expand, shutter-horizontal, shutter-vertical, and fold.

9. Direction / Speed
Direction values: `up / down / left / right`. Not all transitions consume Direction.
Speed values: `slow / normal / fast` and are converted by Runtime into duration.

10. Running the HTML Class
`bf-transition` mounts the target; it does not automatically infer ENTER / EXIT from HTML.
The Consumer obtains the mounted instance and calls the existing Runtime API.

```html
<div
  class="bf-transition"
  data-transition-ui-no="UI-118-PICKER-OPEN"
  data-target-ui-no="UI-040-PICKER"
  data-target-part="panel"
  data-transition="slide-fade"
  data-direction="down"
  data-speed="normal">
  Picker Panel
</div>
<script>
const panel = document.querySelector('.bf-transition[data-target-ui-no="UI-040-PICKER"]');
const transition = BoneTransitionFunctionalClass.getInstance(panel);

async function openPanel() {
  panel.hidden = false;
  await BoneTransition.enter(transition);
}

async function closePanel() {
  await BoneTransition.exit(transition);
  panel.hidden = true;
}
</script>
```

This is a usage example, not a #040 dependency. The same contract applies to menus, panels, pickers, and other Consumers.

11. Consumer / ENTER / EXIT
- Before ENTER: Consumer makes the target displayable.
- ENTER: `BoneTransition.enter(instance)`.
- EXIT: `BoneTransition.exit(instance)`.
- After EXIT: Consumer applies hidden/closed if required.
- Cancel: `BoneTransition.cancel(instance)`.
- Finish immediately: `BoneTransition.finish(instance)`.
Do not confuse Consumer semantic state with #118 motion state.

12. Mount state
After mount:
- `data-bf-transition-mounted="true"`
- `data-bf-transition-runtime="1.0.3"`
Relation Key is `transitionUiNo::targetUiNo::targetPart`.
Use `getInstance(host)` rather than double-mounting the same host.

13. Dynamic elements
The bridge scans the document on DOMContentLoaded. For elements added later, explicitly call `BoneTransitionFunctionalClass.scan(root)` or `mount(host)`. No MutationObserver repair mechanism is used.

14. Reduced Motion
With `data-respect-reduced-motion="true"`, Runtime respects `prefers-reduced-motion: reduce` and applies the required final state without forcing long motion.

15. Security
Blocked input includes non-object, Symbol key, accessor/getter/setter, ASCII control, nested object, unknown Transition, unknown Direction, and unknown Speed. Accessor getters are never evaluated.

16. Property Editor mapping
The test-page Property fields correspond to the formal HTML/Runtime fields: Transition UI Number, Target UI Number, Target Part KEY, Transition, Direction, Speed, and Respect Reduced Motion. Demo-only Preview properties must not be promoted into the formal #118 HTML contract.

17. Functional Class bridge API
`readOptions(host)`, `mount(host)`, `unmount(host)`, `scan(root)`, `getInstance(host)`.
Metadata: `className=bf-transition`, bridge version `1.0.4`, Runtime version `1.0.3`.

18. Public API
The 21 Public API methods remain a separate advanced JavaScript interface:
`defaults`, `normalizeOptions`, `inspectUntrustedInput`, `create`, `destroy`, `isInstance`, `attach`, `detach`, `getOptions`, `setOptions`, `getState`, `getOutput`, `getRelationKey`, `getTarget`, `buildPlan`, `play`, `enter`, `exit`, `cancel`, `finish`, `validate`.

19. Errors / Troubleshooting
- `TRANSITION_FUNCTIONAL_CLASS_RUNTIME_MISSING`: check script order and Runtime version.
- `TRANSITION_FUNCTIONAL_CLASS_RELATION_REQUIRED`: check the three required relation attributes.
- `TRANSITION_FUNCTIONAL_CLASS_BOOLEAN_INVALID`: check reduced-motion Boolean syntax.
- `INVALID_TRANSITION`, `INVALID_DIRECTION`, `INVALID_SPEED`: check formal enum values.
- `RELATION_REQUIRED`: Runtime relation fields are empty.
- `TARGET_UI_NOT_FOUND`: no target is attached to the instance.
- ENTER is invisible: ensure the Consumer made the target displayable and that the target has visible content and dimensions.
- Target remains after EXIT: #118 does not own semantic hidden; the Consumer must apply hidden/closed after EXIT.

20. Smoke Test / Validation
Smoke verifies Runtime identity, 23 Transitions, real ENTER/EXIT, target attach, and related contracts. Validation independently verifies Security, Relation, Functional Class, abnormal cases, and re-ENTER. Smoke alone never becomes ALL PASS.

21. Completion
Completion requires Smoke + Validation success and visual ENTER / EXIT confirmation for all 23 Transitions. Status remains Development until user localhost confirmation.

22. Dependencies / Boundary / Version
Runtime: BoneTransition v1.0.3.
HTML Functional Class: bf-transition v1.0.4.
#118 Runtime does not depend on #117 Animation Runtime or #002 Joint Runtime. The test-page Motion UI Relation Image uses #002 Bone Joint v1.1.36 only for connection evaluation/rendering (`evaluate`, `drawLine`, `drawError`); this does not make Joint a #118 Runtime dependency.
The #046 Consumer on the test page is an example and not a Runtime dependency.
Consumers such as #040 ColorPicker may use #118 when required, but #118 does not depend on #040.
Status: Development until user localhost confirmation.

Test URL:
http://localhost/boneflow/test/bone-transition.html