Skip to content

feat: massively expand motion module and core utilities - #94

Merged
JosunLP merged 44 commits into
devfrom
copilot/expand-animation-and-utility-endpoints
May 21, 2026
Merged

feat: massively expand motion module and core utilities#94
JosunLP merged 44 commits into
devfrom
copilot/expand-animation-and-utility-endpoints

Conversation

Copilot AI commented May 20, 2026

Copy link
Copy Markdown
Contributor

Expand @bquery/bquery/motion and the core utility surface with broad additive APIs. All changes are backward-compatible; no new runtime dependencies.

Motion (@bquery/bquery/motion)

  • Easing: full Penner family (sine/quart/quint/circ/expo/back/elastic/bounce × In/Out/InOut), plus cubicBezier(x1,y1,x2,y2), steps(n, position?), mix(a,b,w), chain(...easings). All registered in easingPresets.
  • Tweens: new animateValue(from,to,opts) rAF driver (numeric/array/object); tween() with pause/resume/reverse/seek/onUpdate/finished; animateTo(el, styles, opts) CSS wrapper; animate() now accepts signal: AbortSignal and playbackRate.
  • Spring: .velocity(v), .set(v), multi-dimensional springVector(dims); new wobbly / slow / molasses presets.
  • Timeline: labels with addLabel(name, at?) and 'label+=100' relative offsets; reverse(), playbackRate(), repeat(n|'infinite'), yoyo(bool), onUpdate(), progress() getter.
  • New primitives: scrollProgress, inView (promise + signal variant), magnetic, tilt, shake, pulse, countUp.
  • Stagger: grid: [columns, rows], from: { x, y } grid origins, axis: 'x' | 'y', and random distance options.
  • Reduced motion: onReducedMotionChange(cb) subscription, reducedMotionSignal() reactive signal.

Utilities (@bquery/bquery/core)

  • array: groupBy, keyBy, partition, zip, range, first, last, take, drop, sample, shuffle (Fisher–Yates), uniqueBy, sortBy (single/multi-selector), intersection, difference, flattenDeep, move, chunkBy.
  • function: memoize (.clear() / .delete()), compose / pipe, curry, partial, retry (backoff + jitter + AbortSignal + shouldRetry). debounce and throttle gain { leading?, trailing?, maxWait? } (debounce) / { leading?, trailing? } (throttle) plus .flush(). The existing (fn, ms) signatures keep identical behavior.
  • object: prototype-pollution-safe deep accessors get(obj, path, default?), set(obj, path, value), has(obj, path) (dot + bracket syntax, dynamic assignment via Object.defineProperty). Adds mapValues, mapKeys, invert, deepEqual (alias isEqual), deep freeze, defaults, typed entriesTyped / keysTyped.
  • string: toSnakeCase, toPascalCase, toTitleCase, pad / padStart / padEnd, wordCount, safe template(str, vars) (string substitution only, 200-char placeholder cap), DOM-free linear-scan stripHtml (not a sanitizer — use @bquery/bquery/security for that), crypto-backed randomString, lines.
  • number: round, roundTo, lerp, inverseLerp, mapRange, formatBytes (decimal/binary, locale-aware via Intl.NumberFormat), randomFloat, sum, average, median, degToRad, radToDeg.
  • misc: RFC 4122 v4 uuid() (crypto.randomUUID() / getRandomValues() fast paths, Math.random() fallback), Go-style sync+async tryCatch, times, pollUntil (timeout + AbortSignal), nextFrame, nextTick.
  • type-guards: isError, isMap, isSet, isRegExp, isSymbol, isBigInt, isAsyncFunction, isIterable, isAsyncIterable, isNullish, isDefined.
  • BQueryUtils interface and the utils namespace include every new entry.

Wiring

  • src/full.ts and src/core/index.ts re-export the new motion/core symbols/types so check:full-bundle stays in sync.
  • CHANGELOG.md [Unreleased] populated; docs/guide/motion.md and docs/guide/api-core.md updated.

Notes / deliberate non-changes

  • Package version intentionally not bumped (no AI-guidance version sync needed).
  • formatNumber is not added under core/utils to avoid colliding with the existing @bquery/bquery/i18n export; utils.formatBytes() accepts a locale option that uses Intl.NumberFormat directly.
  • escapeHtml is not duplicated — continue to import it from @bquery/bquery/security.
  • forms.compose is not re-exported from root or /full to avoid colliding with core.compose; import the validator combinator from @bquery/bquery/forms.

Example

import {
  animateTo, scrollProgress, magnetic, countUp,
  cubicBezier, springVector, reducedMotionSignal,
} from '@bquery/bquery/motion';
import {
  groupBy, sortBy, memoize, retry, get, set, deepEqual,
  uuid, tryCatch, formatBytes, template,
} from '@bquery/bquery/core';

// Motion
const stop = scrollProgress(hero, { onProgress: (p) => hero.style.setProperty('--p', String(p)) });
await countUp(counter, 0, 1_000_000, { duration: 1200, easing: cubicBezier(0.2, 0, 0, 1) });
magnetic(cta, { strength: 0.4 });

// Utilities
const byStatus = groupBy(orders, 'status');
const top = sortBy(orders, [(o) => -o.priority, (o) => o.createdAt]);
const fetchUser = memoize((id: string) => api.getUser(id));
const user = await retry(() => fetchUser('42'), { attempts: 5, baseDelay: 100, factor: 2 });

set(config, 'theme.color.primary', '#0af');                // safe deep set
const same = deepEqual(prev, next);
const [err, data] = await tryCatch(() => api.load());
console.log(template('Uploaded ${size} in ${ms}ms', { size: formatBytes(payload, { locale: 'en-US' }), ms: 42 }));
console.log(uuid());

@JosunLP
JosunLP marked this pull request as ready for review May 20, 2026 06:09
Copilot AI review requested due to automatic review settings May 20, 2026 06:09
@github-actions github-actions Bot added core Changes to the core module motion Changes to the motion module docs Changes to the documentation tests Chenges to the tests build Changes to the build and meta files labels May 20, 2026
@JosunLP
JosunLP changed the base branch from main to dev May 20, 2026 06:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR significantly expands @bquery/bquery/motion and @bquery/bquery/core utilities with a broad set of new, additive APIs (easing presets/factories, tweens, spring vector helpers, timelines, scroll/in-view primitives, micro-interactions, and many new utility helpers), and wires them through the public barrels, /full entry, docs, changelog, and tests.

Changes:

  • Adds major new motion primitives (Penner easing family + factories, rAF tweens, timeline labels/repeat/yoyo/playbackRate, scroll progress + in-view, and micro-interaction effects).
  • Massively expands core utils (array/function/object/string/number/misc + type guards) and exposes them via utils, src/core/index.ts, and src/full.ts.
  • Adds extensive test coverage plus docs and changelog updates for the new surfaces.

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
tests/utils-type-guards-extras.test.ts Tests for new core type-guard utilities.
tests/utils-string-extras.test.ts Tests for new string utilities (case conversion, template, stripHtml, randomString, lines).
tests/utils-object-extras.test.ts Tests for deep object helpers (get/set/has, deepEqual, freeze, defaults, typed keys/entries).
tests/utils-number-extras.test.ts Tests for new number utilities (rounding, mapping, formatBytes, stats, angle conversion).
tests/utils-misc-extras.test.ts Tests for uuid/tryCatch/times/pollUntil/nextFrame/nextTick.
tests/utils-function-extras.test.ts Tests for memoize/compose/pipe/curry/partial/retry and enhanced debounce/throttle.
tests/utils-array-extras.test.ts Tests for new array utilities (groupBy/keyBy/partition/zip/range/etc).
tests/motion-tween.test.ts Tests for animateValue() and tween() controls (pause/seek/stop/abort/delay).
tests/motion-timeline-extras.test.ts Tests for timeline extras, stagger grid/axis/random, reduced-motion subscriptions/signals.
tests/motion-scroll-progress.test.ts Tests for scrollProgress() and inView() behavior and cleanup.
tests/motion-effects.test.ts Tests for magnetic/tilt/shake/pulse/countUp and reduced-motion behavior.
tests/motion-easing.test.ts Tests for new easing family, cubicBezier/steps, mix/chain, presets wiring.
src/motion/types.ts Extends public motion types (Spring velocity/set, SpringVector, timeline labels/repeat/yoyo/progress/onUpdate, AbortSignal/playbackRate options).
src/motion/tween.ts New DOM-free tweening primitives (animateValue/tween) backed by rAF with controls + abort.
src/motion/timeline.ts Timeline enhancements (label parsing, repeat/yoyo, reverse/playbackRate, onUpdate loop).
src/motion/stagger.ts Adds grid/axis/randomized stagger computation (seeded option).
src/motion/spring.ts Adds spring velocity/set, more presets, and new springVector() helper.
src/motion/scroll-progress.ts New scrollProgress() and inView() primitives with cleanup and DOM-less fallbacks.
src/motion/reduced-motion.ts Adds reduced-motion change subscriptions and reducedMotionSignal() reactive adapter.
src/motion/index.ts Re-exports all new motion symbols/types from the motion entry point.
src/motion/effects.ts New micro-interaction effects (magnetic/tilt/shake/pulse/countUp).
src/motion/easing.ts Adds full Penner easing family, cubicBezier/steps factories, mix/chain, and expanded easingPresets.
src/motion/animate.ts Adds AbortSignal cancellation + playbackRate, plus new animateTo() CSS wrapper.
src/full.ts Wires all new core utils + motion exports/types into the /full bundle entry.
src/core/utils/type-guards.ts Adds new type guards (Error/Map/Set/RegExp/Symbol/BigInt/AsyncFunction/Iterable/etc).
src/core/utils/string.ts Adds many string helpers including stripHtml/template/randomString/lines and case conversions.
src/core/utils/object.ts Adds prototype-pollution-safe get/set/has and many object helpers (deepEqual/freeze/defaults/etc).
src/core/utils/number.ts Adds rounding, interpolation helpers, formatBytes, stats helpers, and angle conversions.
src/core/utils/misc.ts Adds uuid/tryCatch/times/pollUntil/nextFrame/nextTick helpers.
src/core/utils/index.ts Expands the utils namespace and BQueryUtils interface with all new utilities.
src/core/utils/function.ts Adds memoize/compose/pipe/curry/partial/retry and enhanced debounce/throttle options + flush.
src/core/utils/array.ts Adds many new array helpers (groupBy/keyBy/sortBy/shuffle/etc).
src/core/index.ts Re-exports all new core utilities + types from the core entry point.
docs/guide/motion.md Documentation updates covering new motion APIs (tweens, timeline labels/repeat/yoyo, scroll/inView, effects, springVector, etc).
docs/guide/api-core.md Documentation updates for expanded utils surface and updated debounce/throttle signatures.
CHANGELOG.md Populates [Unreleased] with detailed entries for motion + utils expansions.
bun.lock Updates lockfile entries for dev tooling versions.

Comment thread src/motion/tween.ts Outdated
Comment thread src/motion/tween.ts
Comment thread src/core/utils/function.ts
Comment thread src/core/utils/string.ts
Comment thread src/core/utils/misc.ts
Comment thread src/motion/reduced-motion.ts Outdated
Comment thread src/motion/stagger.ts Outdated
Comment thread src/motion/timeline.ts Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 5 comments.

Comment thread src/core/utils/object.ts Outdated
Comment thread src/core/utils/string.ts
Comment thread src/motion/reduced-motion.ts Outdated
Comment thread src/motion/animate.ts
Comment thread src/motion/animate.ts

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 38 out of 39 changed files in this pull request and generated 3 comments.

Comment thread src/motion/timeline.ts Outdated
Comment thread src/motion/scroll-progress.ts
Comment thread src/motion/stagger.ts Outdated
Copilot AI requested review from Copilot and removed request for Copilot May 20, 2026 07:03
@JosunLP
JosunLP requested a review from Copilot May 20, 2026 07:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.

Comment thread src/core/utils/function.ts Outdated
Comment thread src/core/utils/object.ts
@JosunLP

JosunLP commented May 20, 2026

Copy link
Copy Markdown
Collaborator

@copilot the tests are failing

Copilot AI commented May 20, 2026

Copy link
Copy Markdown
Contributor Author

@copilot the tests are failing

Fixed in 495a0d1. The failing Test workflow was a bun run test:types compatibility error from Object.hasOwn(...) in tests/utils-object-extras.test.ts; it now uses Object.prototype.hasOwnProperty.call(...), and both bun run test:types and bun test pass locally.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 4 comments.

Comment thread src/core/utils/object.ts Outdated
Comment thread src/motion/tween.ts Outdated
Comment thread src/motion/tween.ts Outdated
Comment thread src/motion/types.ts Outdated
@JosunLP

JosunLP commented May 20, 2026

Copy link
Copy Markdown
Collaborator

@copilot tests and ssr cross runtime build are failing

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Comment thread src/motion/effects.ts
Comment thread src/motion/effects.ts
Comment thread src/motion/tween.ts

Copilot AI commented May 20, 2026

Copy link
Copy Markdown
Contributor Author

@copilot tests and ssr cross runtime build are failing

Fixed in 1228f8b. I investigated the failing Test and SSR cross-runtime runs, and both were failing on the same TypeScript error (src/motion/tween.ts: unused interpolate). I removed the dead helper and re-ran bun run lint, bun run test:types, bun run build, and bun test locally; all pass now.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.

Comment thread src/core/utils/array.ts
Comment thread docs/guide/motion.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.

Comment thread src/motion/effects.ts
Comment thread src/motion/effects.ts

Copilot AI commented May 20, 2026

Copy link
Copy Markdown
Contributor Author

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • https://api.github.com/repos/bQuery/bQuery/pulls/94/reviews/4332698986/comments
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Comment thread src/core/utils/function.ts
Comment thread src/motion/stagger.ts
Comment thread src/motion/types.ts

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Comment thread src/motion/tween.ts
Comment thread src/motion/tween.ts
Comment thread src/core/utils/function.ts

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Comment thread src/motion/animate.ts Outdated
Comment thread src/motion/tween.ts
Comment thread src/core/utils/object.ts

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Comment thread tests/utils-object-extras.test.ts
Comment thread src/core/utils/string.ts Outdated
Comment thread src/core/utils/object.ts

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.

Comment thread src/core/utils/misc.ts
Comment thread src/motion/spring.ts Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated no new comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

build Changes to the build and meta files core Changes to the core module docs Changes to the documentation motion Changes to the motion module tests Chenges to the tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants