Skip to content

docs: formalize the reactive contract (trigger keys, frozen parameters, cancel-and-restart) #91

Description

@l2hyunwoo

Summary

#84 made key-driven recompilation work. What is missing is a written contract for what callers may rely on. Three rules, each verified against the runtime source:

  1. Every value read inside content is frozen at compile time. The internal composition is created, composed once, and disposed (Jindong.kt:120-127); there is no recomposition path. Keys are the only recompile trigger.
  2. Keys are playback triggers. Put state in keys exactly when its change should fire playback. A slider value passed as a key fires a vibration on every drag step; state that only shapes the pattern belongs inside content. The sample app hit this distinction in review (feat: rebuild sample app as an 8-screen haptic verification harness #86).
  3. Cancel-and-restart is best effort. A key change cancels the in-flight playback before starting the new one, with ordering guaranteed by the manager's state lock (HapticManager.kt:126-149). Neither Vibrator.cancel() nor CHHapticPatternPlayer.stop reports completion, so a few milliseconds of physical overlap are possible.

Scope

  • KDoc on Jindong plus a documentation page covering the three rules.
  • Document the value-embedding idiom Jindong(pattern) { Clip(pattern) }. A Jindong(pattern, vararg keys) overload was prototyped and dropped: Jindong(p) { ... } resolves to the existing vararg overload with p as a key, which compiles and silently plays the lambda instead of the pattern.
  • Regression tests: a parameter change without a key must not re-fire; a key change must.

Related: #56 covers suppressing playback on initial composition, which belongs to the same contract.

Depends on #90.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions