Transition

Transition base prototype

<wc-base-transition open appear class="transition-wrapper">
  <div class="w-64 h-40 rounded-xl flex flex-col items-center justify-center text-white shadow-xl transition-box">
    <span class="text-lg font-semibold">Animated Box</span>
  </div>
</wc-base-transition>

<style>
/* 宿主通过 data-transition-state 属性驱动样式 */
.transition-wrapper[data-transition-state="closed"] .transition-box {
  opacity: 0;
  transform: scale(0.95) translateY(-10px);
}

.transition-wrapper[data-transition-state="entering"] .transition-box {
  opacity: 0.7;
  transform: scale(0.98) translateY(-2px);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

.transition-wrapper[data-transition-state="entered"] .transition-box {
  opacity: 1;
  transform: scale(1) translateY(0);
}

.transition-wrapper[data-transition-state="leaving"] .transition-box {
  opacity: 0.5;
  transform: scale(0.98) translateY(2px);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}
</style>

This demo shows imperative state-machine control.

• Enter: Moves into entering from any valid state (closed → entering or leaving → entering). Ignored if already entering or entered.
• Leave: Moves into leaving from any valid state (entered → leaving or entering → leaving). Ignored if already leaving or closed.
• Complete: Advances entering to entered, or leaving to closed.

Typical full flow:

Enter → Complete → Leave → Complete

<wc-base-transition class="transition-wrapper">
  <div class="w-64 h-40 rounded-xl flex flex-col items-center justify-center text-white shadow-xl transition-box cursor-pointer select-none">
    <span class="text-lg font-semibold">Click Me</span>
  </div>
</wc-base-transition>

<style>
/* 宿主通过 data-transition-state 属性驱动样式 */
.transition-wrapper[data-transition-state="closed"] .transition-box {
  opacity: 0;
  transform: scale(0.95) translateY(-10px);
}

.transition-wrapper[data-transition-state="entering"] .transition-box {
  opacity: 0.7;
  transform: scale(0.98) translateY(-2px);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

.transition-wrapper[data-transition-state="entered"] .transition-box {
  opacity: 1;
  transform: scale(1) translateY(0);
}

.transition-wrapper[data-transition-state="leaving"] .transition-box {
  opacity: 0.5;
  transform: scale(0.98) translateY(2px);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}
</style>

This demo drives the state machine through the open prop. Transition uses enterDuration / leaveDuration as a host-neutral completion fallback; a host may also call complete() when its native animation finishes earlier.

• Toggle Open: Flips the open value.
  • If currently closed / leaving, setting open=true triggers entering → entered.
  • If currently entered / entering, setting open=false triggers leaving → closed.
• Click Me: Clicking the box itself also toggles open, behaving the same as the button.

Typical flow:

Toggle Open (show) → Toggle Open (hide)

In this demo the CSS transition is set to 0.3s, so entering and leaving will auto-complete after that duration.

Transition is a low-level foundational component for managing the presence lifecycle of elements. It does not render visible content itself; instead, it provides state machine governance, allowing the host platform (CSS, React, Vue, etc.) to drive actual animations based on the state.

asTransition() is a no-argument ordinary once asHook exported by @proto.ui/prototypes-base. Repeated calls in one setup chain return the same projected handle. It governs only the perceptual closed / entering / entered / leaving phases and submits structural intent through run.lifecycle.setPresent() and L1 ViewIntent.

It does not require module ports or host-private facades. Lifecycle callbacks, run.lifecycle.setPresent(), and Core delay() provide the complete public capability boundary needed to implement the policy.

Transition, ViewIntent, and the actual view epoch remain separate facts:

transitionState: closed → entering → entered → leaving → closed
ViewIntent:      detached ↔ present
view epoch:      detached ↔ mounting ↔ mounted ↔ unmounting

• Enter: ViewIntent becomes present first. The state enters entering only after the new view epoch mounts, preventing partially committed DOM from being revealed.
• Leave: The current view is retained throughout leaving; ViewIntent becomes detached only after completion into closed.
• Restore: Detaching does not dispose the Proto instance. Controls, state, and prop watchers remain alive and can create a fresh view epoch later.

This makes the state machine work correctly with CSS transitions, because the DOM element is guaranteed to exist during entering and leaving even when the adapter would otherwise remove it immediately.

ViewIntent is Transition’s only structural-intent path. isPresent is perceptual only, and closed does not mean the Proto instance has been disposed.

• RuntimeSession continues syncing props and dispatching watchers while detached, so controlled open=false → true can request its own view without a mount-before-update deadlock.
• Adapter owners retain the Proto instance and create or release React, Vue, or WC view epochs from the latest ViewIntent.
• The reveal barrier keeps a fresh view hidden until its first commit and effects replay are coherent; React/Vue no longer need a double-RAF baseline.

This separation means:

1. Transition users deal only with the state machine. Structural coordination goes through run.lifecycle.setPresent() rather than adapter-specific APIs.
2. Adapters deal only with ViewIntent and view epochs. React, Vue, and WC do not need to interpret the business difference between entering and entered.
3. A Proto instance can survive across view epochs. React/Vue may render null, while WC may release its internal view; neither operation loses controls or prototype state.

Transition only manages logical state. If you do not provide CSS for data-transition-state="entering" and data-transition-state="leaving", the element will appear/disappear instantly when complete() is called.

By default Transition completes after enterDuration / leaveDuration. If the host animation finishes earlier, observe that signal and call controls.complete(); the stale fallback task is canceled.

Typical controlled-mode wiring:

// After setting open=true and applying CSS transition
el.addEventListener('transitionend', () => {
  exposes.controls.complete();
});

If you want an element to animate in when it first renders, set appear: true. Otherwise the element will jump straight to entered on mount without playing the enter animation.

• 'reverse' (default): Best for most UI (menus, tooltips). If the user toggles quickly, the animation reverses direction smoothly.
• 'wait': Best when you must guarantee every transition finishes (e.g. a multi-step wizard whose background panel should not skip animations).
• 'immediate': Best for snappy stateless toggles where you do not care about partial animations. The current animation is discarded and the new one starts from a clean state.

Always use the exposed controls (controls.enter(), controls.leave(), controls.complete()) or the open prop. Mutating transitionState directly bypasses the state-machine and ViewIntent ordering constraints.

Transition retains the current view during leaving. Avoid destroying child state (such as tearing down a <video> or canceling requests) until closed or the actual view-unmount lifecycle.

closed → entering → entered → leaving → closed

• closed: Perceptually absent; it normally requests a detached ViewIntent but does not mean the Proto instance is disposed
• entering: Entering animation in progress, DOM exists, entering styles applied
• entered: Fully visible, stable state
• leaving: Leaving animation in progress, DOM still exists, leaving styles applied

Accessed via the controls expose:

• enter(): Trigger enter
• leave(): Trigger leave
• complete(): Mark current transition complete, advance to next state

base-transition v0 only manages the presence lifecycle of a single element (closed → entering → entered → leaving → closed).

Nested exit coordination (e.g., an outer Dialog waiting for an inner child to finish leaving before closing) belongs to a separate transition-group / boundary abstraction and is intentionally out of scope for v0.