Skip to content

Add core swirl option - #5

Merged
aomona merged 2 commits into
mainfrom
feat/core-swirl-option
May 24, 2026
Merged

Add core swirl option#5
aomona merged 2 commits into
mainfrom
feat/core-swirl-option

Conversation

@aomona

@aomona aomona commented May 24, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add a core swirl mesh option and carry it through generated CSS and React helpers
  • Include swirl in playground CSS export so the live control is reproducible from the API
  • Document the option and add coverage for neutral, clamped, and animated swirl output

Tests

  • npm test
  • npm run lint
  • npm run format:check

Summary by CodeRabbit

  • New Features

    • Added swirl parameter support to mesh gradients for enhanced customization.
    • Swirl control now available in Core CSS (swirl: 0–100) and React (swirl={value}) implementations.
  • Documentation

    • Updated README with swirl usage examples.
    • Extended API documentation with swirl option details and configuration guidance.
    • Enhanced playground with live swirl adjustment controls.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 24, 2026

Copy link
Copy Markdown

Warning

Review limit reached

@aomona, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 53 minutes and 52 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a0fd2553-5244-40c1-834a-9ed0ed7c3911

📥 Commits

Reviewing files that changed from the base of the PR and between 96e4e0a and 0ed79bf.

📒 Files selected for processing (2)
  • src/react.tsx
  • tests/library.test.mjs
📝 Walkthrough

Walkthrough

This PR introduces a swirl parameter that rotates and repositions the mesh gradient layer. Swirl is clamped to 0–100 range and affects CSS transforms, background sizing/positioning, and motion keyframe animations across TypeScript, React, playground, and test implementations.

Changes

Swirl feature implementation

Layer / File(s) Summary
Swirl interface and utility functions
src/core.ts
MeshGradientOptions gains optional swirl field; new helpers normalizeSwirl, createSwirlTransform, and shiftedPosition compute clamped values and derive CSS transforms, scale/rotation, and background positioning offsets.
Core gradient CSS with swirl integration
src/core.ts
createGrainGradientCSS normalizes swirl, conditionally applies swirl-dependent background-size and background-position CSS, and combines computed swirl transform with existing blur/saturation effects.
Motion keyframes with swirl transforms
src/core.ts
createGrainGradientMotionCSS extends drift, breathe, and orbit keyframes to incorporate swirl-based transforms and swirl-shifted background-position offsets throughout animation cycles.
React hook swirl integration and mesh styling
src/react.tsx
React hook adds swirl helpers, includes options.swirl in memoization keys, reworks mesh layer styling with swirl-dependent background sizing/positioning, and exposes CSS variables for animation keyframes.
React motion keyframes with swirl variables
src/react.tsx
Motion CSS generation replaces hardcoded keyframe transforms with dynamic swirl CSS variables, allowing animations to respond to computed swirl scale and rotation.
Playground UI and CSS export
playground/index.html
Mesh background sizing baseline adjusted for swirl calculations; CSS export includes current swirl state in createGrainGradientCSS options.
Test suite for swirl option
tests/library.test.mjs
Test cases verify swirl remains neutral by default, enabled swirl produces correct CSS output, values above 100 are clamped, and swirl effects persist with motion animations.
API docs and usage examples
README.md, docs/API.md
Add swirl: 30 to Core CSS and React examples; document swirl in createMeshGradient options with 0–100 clamping range; clarify how swirl modifies mesh layer background properties and transforms.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • aomona/grain-gradient#3: Both PRs modify the same motion/CSS pipeline—createGrainGradientMotionCSS/motion keyframes in src/core.ts and the useGrainGradient motion CSS injection in src/react.tsx—with the main PR extending those existing drift/breathe/orbit transforms to additionally apply swirl.

Poem

🌀 A swirl joins the dance,
Mesh layers spin and prance,
Transforms twirl with grace,
Keyframes find their place,
Gradients now enchant! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title "Add core swirl option" directly and clearly matches the PR's main objective to add a core swirl mesh option across the codebase.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/core-swirl-option

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🧹 Nitpick comments (1)
tests/library.test.mjs (1)

57-63: ⚡ Quick win

Add lower-bound clamp coverage for swirl (< 0).

Current tests validate clamping above 100, but not below 0, even though the contract is 0–100. Add one negative-value case to lock that behavior.

Proposed test addition
 test("clamps swirl above 100", () => {
   const css = createGrainGradientCSS({ swirl: 999 });
   assert.ok(css.includes("background-size: 155.0% 140.0%"));
   assert.ok(css.includes("background-position: 62.0% 40.0%"));
   assert.ok(css.includes("scale(1.400)"));
   assert.ok(css.includes("rotate(12.00deg)"));
 });
+
+test("clamps swirl below 0", () => {
+  const css = createGrainGradientCSS({ swirl: -20 });
+  assert.ok(!css.includes("background-position:"));
+  assert.ok(!css.includes("rotate("));
+  assert.ok(!css.includes("scale(1.12) translate3d"));
+});
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/library.test.mjs` around lines 57 - 63, Add a test case in
tests/library.test.mjs to verify swirl values below 0 are clamped to 0: create a
new test (e.g., "clamps swirl below 0") that calls createGrainGradientCSS({
swirl: -1 }) and asserts the generated CSS matches the expected output for swirl
0 (same background-size, background-position, scale and rotate strings used in
the existing "clamps swirl above 100" test); this ensures createGrainGradientCSS
enforces the 0–100 contract for negative inputs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/react.tsx`:
- Around line 21-35: normalizeSwirl currently returns full-precision derived
numbers; update it to match the rounding/formatting used in src/core.ts so React
output matches API CSS. Keep clamp(swirl) and enabled logic, but round the
derived fields (scale, rotate, offsetX, offsetY, backgroundSizeX,
backgroundSizeY, backgroundPositionX, backgroundPositionY and any intermediate
shift if used for calculations) to the same precision/formatting as core.ts
before returning; reference the normalizeSwirl function and ensure the returned
object properties use the rounded values.

---

Nitpick comments:
In `@tests/library.test.mjs`:
- Around line 57-63: Add a test case in tests/library.test.mjs to verify swirl
values below 0 are clamped to 0: create a new test (e.g., "clamps swirl below
0") that calls createGrainGradientCSS({ swirl: -1 }) and asserts the generated
CSS matches the expected output for swirl 0 (same background-size,
background-position, scale and rotate strings used in the existing "clamps swirl
above 100" test); this ensures createGrainGradientCSS enforces the 0–100
contract for negative inputs.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 64152de8-61a9-4873-9861-f553274fa606

📥 Commits

Reviewing files that changed from the base of the PR and between f66ec51 and 96e4e0a.

📒 Files selected for processing (6)
  • README.md
  • docs/API.md
  • playground/index.html
  • src/core.ts
  • src/react.tsx
  • tests/library.test.mjs

Comment thread src/react.tsx
@aomona
aomona merged commit cbcaaf6 into main May 24, 2026
1 check passed
@aomona
aomona deleted the feat/core-swirl-option branch May 24, 2026 02:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant