feat(raf): add frameloop utils.

[royeden]

• Added useFrameloop util to use unified request animation frame calls.
• Added createScheduledFrameloop to handle request animation frame from external sources.
• Fixed createRAF cleanup for id 0 by using null instead.

Addresses this proposal #822.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d005f2e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[atk]

The explanation is way too complex. "A version of createRAF that batches multiple frames within the same render cycle instead of skipping them ."

[atk]

You seem to have forgotten to update the README.md

[royeden]

Yes, sorry for that!

[atk]

Not that I generally dislike this addition, but why not extract the queue logic into a separate primitive that can also be used with the normal createRAF?

[royeden]

Could I get some guidance on how that would be structured? Do you propose adding the queue logic as a separate create helper?

[atk]

Something like

function queueCallbacks(
  ...initialCallbacks: (() => void)[]
): [callback: () => void, { add: (cb) => void, del: (cb) => void }] {
  ...
}

[royeden]

Sorry for the delay on this, the end of the year tends to be really busy. I was starting to re-visit the approach itself and maybe landed into a nicer primitive set, want to hear your opinions on this @atk (I can leave it as an update on this PR, but I don't think this is the right approach for this):

createFrameScheduler

A function with this signature that allows scheduling with external frameloop utils like motion's frame:

type CreateScheduledFrame<Callback extends (...args: any) => any> = 
  (callback: Callback) => [running: Accessor<boolean>, start: VoidFunction, stop: VoidFunction];

createFrameScheduler<
  // NonNullable is used here so we know nothing is scheduled when the value is `null`
  RequestID extends NonNullable<unknown>,
  Callback extends (...args: any) => any
>(
  schedule: (callback: Callback) => RequestID,
  cancel: (requestID: RequestID) => void,
): CreateScheduledFrame<Callback>

createFrameloopScheduler

A function with this signature that allows scheduling with functions that need to run in a loop for the callback to re-run:

type CreateScheduledLoop<Callback extends (...args: any) => any> = 
  (callback: Callback) => [running: Accessor<boolean>, start: VoidFunction, stop: VoidFunction];

createFrameScheduler<
  // NonNullable is used here so we know nothing is scheduled when the value is `null`
  RequestID extends NonNullable<unknown>,
  Callback extends (...args: any) => any
>(
  schedule: (callback: Callback) => RequestID,
  cancel: (requestID: RequestID) => void,
): CreateScheduledLoop<Callback>

Why?

These primitives would allow us to compose any handlers with the running, start, stop logic, so you could basically do create your own utils (not 100% sure if these should exist under the raf package anymore either).

They both work with the same implementation that is used in createRAF.

Examples:

createRAF (requestAnimationFrame):

export const createRAF = createFrameloopScheduler(
  window.requestAnimationFrame,
  window.cancelAnimationFrame
);

createRIC (requestIdleCallback):

export const createRIC = createFrameloopScheduler(
  window.requestIdleCallback,
  window.cancelIdleCallback
);

export const createRIC100ms = createFrameloopScheduler(
  (callback: IdleRequestCallback) => window.requestIdleCallback(callback, { timeout: 100 }),
  window.cancelIdleCallback
);

motion's frame utils:

import { cancelFrame, frame } from 'motion';
export const createMotionRead = createScheduledFrame(
  callback => frame.read(callback, true),
  cancelFrame
);

export const createMotionUpdate = createScheduledFrame(
  callback => frame.update(callback, true),
  cancelFrame
);

export const createMotionRender = createScheduledFrame(
  callback => frame.render(callback, true),
  cancelFrame
);

[atk]

I don't see my last points addressed, also, the tests seem to fail.

[atk]

You need to add your primitives to primitive.list.