feat: aspect-ratio & crop configs

[tsi]

Aspect ratio & crop mode as top-level source props

Summary

Add aspectRatio, cropMode, and cropPadColor as top-level source options. The player merges these into the Cloudinary transformation internally, so consumers no longer need to construct transformation.aspect_ratio, transformation.crop, etc. manually.

Changes

API

• New source options: aspectRatio, cropMode, cropPadColor
• Passed via player.source() or data-cld-source:

player.source({
  publicId: 'sea_turtle',
  aspectRatio: '16:9',
  cropMode: 'fill',    // or 'pad', 'smart'
  cropPadColor: 'blue' // for pad mode only
});

Crop modes

cropMode	Cloudinary equivalent	Notes
fill	c_fill	Crops to fit aspect ratio
pad	c_pad + background	Letterboxes; uses cropPadColor for background
smart	c_fill + g_auto	AI-based crop, no distortion

Implementation

• normalizeAspectCrop in cloudinary plugin: Merges top-level props into transformation before processing
• smart mapping: Uses fill + gravity: 'auto' (instead of fill_pad) to avoid distortion with aspect_ratio

Files touched

File	Change
src/video-player.const.js	Added to SOURCE_PARAMS
src/plugins/cloudinary/index.js	normalizeAspectCrop merge logic
src/config/configSchema.json	Schema for aspectRatio, cropMode, cropPadColor
src/validators/validators.js	Validators for new props
src/utils/get-analytics-player-options.js	Include in source options for analytics
docs/aspect-ratio-crop.html	New example page (NonESM)
docs/es-modules/aspect-ratio-crop.html	New example page (ESM)
docs/index.html	Link to aspect-ratio-crop
docs/es-modules/index.html	Link to aspect-ratio-crop
test/unit/videoSource.test.js	Unit test for sourceOptions extraction
test/e2e/*	POM, specs, LINKS/ESM_LINKS for E2E

Example pages

• fill (1:1): Crops to fit
• pad (4:3): Letterboxes with blue background
• smart (9:16): AI crop for portrait

Testing

• Unit: pnpm test:unit (videoSource extracts aspectRatio, cropMode, cropPadColor)
• E2E: pnpm test:e2e (NonESM + ESM aspect-ratio-crop page)

[netlify]

✅ Deploy Preview for cld-video-player ready!

Name	Link
🔨 Latest commit	6fc8ba5
🔍 Latest deploy log	https://app.netlify.com/projects/cld-video-player/deploys/69aeed3de5f9ea0007c6da22
😎 Deploy Preview	https://deploy-preview-996--cld-video-player.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for cld-vp-esm-pages ready!

Name	Link
🔨 Latest commit	6fc8ba5
🔍 Latest deploy log	https://app.netlify.com/projects/cld-vp-esm-pages/deploys/69aeed3daac2e800082a8fe5
😎 Deploy Preview	https://deploy-preview-996--cld-vp-esm-pages.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[adimiz1]

I learned a lot from this, thanl you!