haltu / muuri

Infinite responsive, sortable, filterable and draggable layouts
https://muuri.dev
MIT License
10.77k stars 643 forks source link

Docs: Be more explicit on the dragStartPredicate return #544

Open karmaral opened 1 year ago

karmaral commented 1 year ago

Hello! The docs could be more explicit in regards to the return type of dragStartPredicate. Currently it says

..it will be called until you return true or false.

I only realized this was implying that not returning true or false would re-run the function by examining the touch delay example.

Looking back I see there's just empty returns on the examples, but for at-a-glance reads, perhaps it would add value to have it more explicitly defined in the description.

Could be something as simple as highlighting until.

Do you agree? Or is it too fine grained?

niklasramo commented 1 year ago

Reading the docs again I think it indeed makes sense to emphasize that. Maybe something like this?

If you provide a function you can customize the drag start logic as you please. When the user starts to drag an item this predicate function will be called on every pointer/touch/mousemove event until you return true or false. If you return true the item will begin to move whenever the item is dragged. If you return false the item will not be moved at all. You should return undefined if you want to keep the predicate in "pending" state. Note that after you have returned true or false this function will not be called until the item is released and dragged again.

karmaral commented 1 year ago

Yeah, that's much clearer!