{"_id":"@alekstar79/media-tracker","name":"@alekstar79/media-tracker","dist-tags":{"latest":"2.0.0"},"versions":{"2.0.0":{"name":"@alekstar79/media-tracker","version":"2.0.0","description":"Processing media queries via browser API from JavaScript","type":"module","private":false,"main":"./dist-lib/media-tracker.umd.js","module":"./dist-lib/media-tracker.es.js","types":"./dist-lib/index.d.ts","exports":{".":{"import":"./dist-lib/media-tracker.es.js","require":"./dist-lib/media-tracker.umd.js","types":"./dist-lib/index.d.ts"},"./style":"./dist-lib/media-tracker.css"},"keywords":["media-queries","responsive","breakpoints","tracker","typescript","matchmedia"],"author":{"name":"Aleksey Tarasenko","email":"alekstar79@yandex.ru"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/alekstar79/media-tracker.git"},"homepage":"https://github.com/alekstar79/media-tracker#readme","bugs":{"url":"https://github.com/alekstar79/media-tracker/issues"},"publishConfig":{"access":"public"},"scripts":{"dev":"vite","build":"vite build","build:lib":"vite build --config vite.lib.config.ts","preview":"vite preview","docs":"jsdoc -c jsdoc.config.json","prepublishOnly":"npm run build:lib && npm test","pub:dry-run":"npm run build:lib && npm publish --dry-run","pub:beta":"npm run build:lib && npm publish --tag beta","pub:patch":"npm version patch && npm run build:lib && npm publish","pub:minor":"npm version minor && npm run build:lib && npm publish","pub:major":"npm version major && npm run build:lib && npm publish","test":"echo \"No tests yet\" && exit 0"},"devDependencies":{"@babel/cli":"^7.28.3","@babel/core":"^7.28.5","@babel/preset-env":"^7.28.5","@babel/preset-typescript":"^7.28.5","@types/node":"^24.9.1","docdash":"^2.0.2","jsdoc":"^4.0.2","jsdoc-babel":"^0.5.0","typescript":"^5.0.0","vite-plugin-dts":"^4.5.4","vite":"^5.0.0"},"_id":"@alekstar79/media-tracker@2.0.0","gitHead":"1632966ecd617f559a668ff140b1e511237bc4fe","_nodeVersion":"18.20.3","_npmVersion":"10.7.0","dist":{"integrity":"sha512-mfkLp+4Fk7sq43M4T3fTw8epBwWzYhYnGHGy/w5usFUFFytZKYRh7o4/1gVvUUmpUKDRJkeHNeoybAwD8BjrnA==","shasum":"35f4e45c5ddc389cdbeb054bda5805ea839d4e88","tarball":"https://registry.npmjs.org/@alekstar79/media-tracker/-/media-tracker-2.0.0.tgz","fileCount":7,"unpackedSize":26143,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG/O2zfRmxaxJGN29xedOk6qxU4d11w4CJmn2Yw5i0usAiBOI6UAtao61EctQeFIvCoS1NfpMGrpicx2Sqp1KmriwQ=="}]},"_npmUser":{"name":"alekstar79","email":"alekstar79@yandex.ru"},"directories":{},"maintainers":[{"name":"alekstar79","email":"alekstar79@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/media-tracker_2.0.0_1761661070339_0.0010053921443990976"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-28T14:17:50.219Z","2.0.0":"2025-10-28T14:17:50.549Z","modified":"2025-10-28T14:17:50.846Z"},"maintainers":[{"name":"alekstar79","email":"alekstar79@yandex.ru"}],"description":"Processing media queries via browser API from JavaScript","homepage":"https://github.com/alekstar79/media-tracker#readme","keywords":["media-queries","responsive","breakpoints","tracker","typescript","matchmedia"],"repository":{"type":"git","url":"git+https://github.com/alekstar79/media-tracker.git"},"author":{"name":"Aleksey Tarasenko","email":"alekstar79@yandex.ru"},"bugs":{"url":"https://github.com/alekstar79/media-tracker/issues"},"license":"ISC","readme":"# Media Tracker TS\n\n[](https://www.npmjs.com/package/@alekstar79/media-tracker)\n[](https://github.com/alekstar79/media-tracker)\n[]()\n[]()\n[]()\n\nA lightweight, high-performance TypeScript library for tracking media queries and responsive breakpoints in modern web applications.\n\n\n\n## ๐ฎ Demo\n\nCheck out the live demo: [Media Tracker Demo](https://alekstar79.github.io/media-tracker)\n\nThe demo shows real-time breakpoint tracking with toast notifications and demonstrates all library features in action.\n\n## ๐ Features\n\n- ๐ชถ Lightweight - Zero dependencies, minimal footprint\n- ๐ฑ Responsive - Track any breakpoint configuration\n- โก High Performance - Uses native MediaQueryList API with debouncing\n- ๐ท TypeScript - Fully typed with comprehensive documentation\n- ๐ฏ Precise - Binary search algorithm for optimal breakpoint matching\n- ๐ ๏ธ Flexible - Customizable breakpoints and debounce timing\n- ๐ฆ Dual Build - Support for ES modules, CommonJS, and UMD\n\n## ๐ Project Structure\n\n```text\nmedia-tracker/\nโโโ src/\nโ โโโ lib/ # Library core\nโ โ โโโ constants.ts # Breakpoint constants\nโ โ โโโ media-tracker.ts # Main MediaTracker class\nโ โ โโโ index.ts # Library entry point\nโ โโโ demo/ # Demo application\nโ โ โโโ emitter.ts # Event emitter (demo only)\nโ โ โโโ notifications.ts # Toast notifications\nโ โ โโโ media-handler.ts # Demo media handler\nโ โ โโโ index.ts # Demo entry point\nโ โโโ styles/\nโ โ โโโ style.css # Demo styles\nโ โโโ index.html # Demo HTML\nโโโ dist/ # Demo build output\nโโโ dist-lib/ # Library build output\nโโโ docs/ # Generated documentation\n```\n\n## ๐ฆ Installation\n\n**Library Installation:**\n\n```shell\nyarn install @alekstar79/media-traker\n```\n**Development Setup:**\n\n```shell\ngit clone git@github.com:alekstar79/media-tracker.git\ncd media-tracker\nyarn install\n```\n\n## ๐ป Usage\n\n### ๐ ES Modules (Recommended)\n\n```ts\nimport { MediaTracker, W768, W1024, W1200 } from 'media-tracker';\n\nconst tracker = MediaTracker.create(\n [W768, W1024, W1200],\n (state) => {\n console.log('Current media state:', state);\n \n if (state.width === W768) {\n // Mobile layout\n } else if (state.width === W1024) {\n // Tablet layout \n } else if (state.width === W1200) {\n // Desktop layout\n }\n },\n 150 // Optional debounce time (ms)\n)\n```\n\n### ๐ฆ CommonJS\n\n```js\nconst { MediaTracker, W768, W1024 } = require('media-tracker')\n\nconst tracker = MediaTracker.create([W768, W1024], (state) => {\n console.log('Media state changed:', state)\n})\n```\n\n### ๐ In Browser (UMD)\n\n```html\n\n\n```\n\n## ๐ Available Breakpoints\n\n```ts\nimport {\n W0, // 0px - ๐ฑ Base mobile\n W240, // 240px - ๐ฑ Very small mobile\n W320, // 320px - ๐ฑ Small mobile\n W480, // 480px - ๐ฑ Mobile landscape\n W640, // 640px - ๐ Small tablets\n W768, // 768px - ๐ Tablets\n W991, // 991px - ๐ฅ๏ธ Small desktops\n W1024, // 1024px - ๐ฅ๏ธ Desktop screens\n W1200, // 1200px - ๐ฅ๏ธ Large desktop\n W1280, // 1280px - ๐ฅ๏ธ HD desktop\n W1728, // 1728px - ๐ฅ๏ธ Large HD\n W1920, // 1920px - ๐ฅ๏ธ Full HD\n W1980, // 1980px - ๐ฅ๏ธ Large Full HD\n W3840, // 3840px - ๐บ 4K Ultra HD\n W4096 // 4096px - ๐บ Maximum\n} from 'media-tracker'\n```\n\n## ๐จ Development\n\n๐ **Start development server:**\n```shell\nyarn dev\n```\n\nStarts Vite development server at http://localhost:3000\n\n๐ฆ **Build for production:**\n```shell\nyarn build # ๐๏ธ Build demo application\nyarn build:lib # ๐ฆ Build library for distribution\n```\n\n๐ **Preview production build:**\n```shell\nyarn preview\n```\n\n๐ **Generate documentation:**\n```shell\nyarn docs\n```\n\n## โ๏ธ Configuration\n\n**MediaTracker Options**\n\n| Option | Type | Default | Description |\n|----------------|-------------------------------|----------|-------------------------------------------------|\n| `widths` | `number[]` | Required | Array of breakpoint widths to track |\n| `handler` | `(state: MediaState) => void` | Required | Callback function for media changes |\n| `debounceTime` | `number` | `100` | Debounce time in milliseconds for resize events |\n\n**MediaState Object**\n\n```ts\ninterface MediaState {\n width?: number; // Current viewport width (when exact match)\n maxWidth?: number; // Next larger breakpoint \n minWidth?: number; // Next smaller breakpoint\n}\n```\n\n## ๐ API Reference\n\n### MediaTracker Class\n\n โก Static Methods\n\nMediaTracker.create(widths, handler, debounceTime?)\n\n1. Creates and initializes a new MediaTracker instance\n2. Parameters:\n\n - widths: number[] - Breakpoint widths to track\n - handler: (state: MediaState) => void - Change callback\n - debounceTime?: number - Debounce time (ms), default: 100\n\n3. Returns: MediaTracker instance\n\n ๐ง Instance Methods\n\nsetWidths(widths)\n\n- Updates the breakpoint configuration\n- Parameters: widths: number[] - New breakpoint array\n- Returns: MediaTracker instance (chainable)\n\nsetHandler(handler)\n\n- Updates the change handler function\n- Parameters: handler: (state: MediaState) => void - New callback\n- Returns: MediaTracker instance (chainable)\n\nonTrack()\n\n- Starts tracking media queries and resize events\n- Returns: MediaTracker instance (chainable)\n\nnearestWidths()\n\n- Calculates current media state\n- Returns: MediaState object\n\n## ๐ Lifecycle\n\n1. ๐ **Initialization** - Create instance with breakpoints and handler\n2. ๐ก **Tracking Start** - Media queries and resize listeners are set up\n3. ๐ **State Changes** - Handler is called on breakpoint changes\n4. ๐งน **Automatic Cleanup** - Listeners are managed internally\n\n## ๐๏ธ Performance Tips\n\n1. ๐ฏ Minimize Breakpoints - Only track breakpoints you actually use\n2. โฐ Optimize Debounce - Increase debounce time for complex handlers\n3. ๐ฏ Use Exact Matches - Handler receives exact matches when available\n4. ๐ฆ Batch Updates - Use requestAnimationFrame in complex UIs\n\n```ts\n// โ
Good: Minimal breakpoints\nMediaTracker.create([W768, W1024, W1200], handler)\n\n// โ
Better: Increased debounce for heavy operations \nMediaTracker.create(breakpoints, heavyHandler, 250)\n```\n\n## โ Troubleshooting\n\n**Check imports:**\n\n```ts\n// โ
Correct\nimport { MediaTracker, W768 } from 'media-tracker'\n\n// โ Incorrect \nimport MediaTracker from 'media-tracker'\n```\n\n**Verify breakpoints:**\n\n```ts\n// โ
Breakpoints must be sorted and unique\nMediaTracker.create([768, 1024, 1200], handler) // โ Works\nMediaTracker.create([1200, 768], handler) // โ Auto-sorted\nMediaTracker.create([], handler) // โ Throws error\n```\n\n**Check handler:**\n\n```ts\n// โ
Handler must be a function\nMediaTracker.create(breakpoints, console.log) // โ Works\nMediaTracker.create(breakpoints, (state) => {/*...*/}) // โ Works \nMediaTracker.create(breakpoints, 'not a function') // โ Throws error\n```\n\n## ๐ Common Issues\n\n**Handler not called on initial load:**\n\n- MediaTracker automatically calls handler with initial state\n- Check browser console for errors\n\n**Resize events too frequent:**\n\n- Increase debounceTime parameter\n- Default is 100ms, try 150-250ms for better performance\n\n**Breakpoints not matching:**\n\n- Ensure breakpoints are in pixels\n- Verify viewport meta tag in HTML:\n``\n\n\n## ๐ Browser Support\n\n| Browser | Version | Support |\n|--------------------|---------|---------|\n| ๐ข Chrome | 41+ | โ
Full |\n| ๐ข Firefox | 47+ | โ
Full |\n| ๐ข Safari | 10.1+ | โ
Full |\n| ๐ข Edge | 16+ | โ
Full |\n| ๐ข iOS Safari | 10.3+ | โ
Full |\n| ๐ข Android Browser | 56+ | โ
Full |\n\n**Required APIs:**\n\n- window.matchMedia (CSSOM View Module)\n- ResizeObserver (for demo features)\n- ES2015+ features (arrow functions, const/let, classes)\n\n\n## ๐งฉ Polyfills (if needed)\n\nFor older browsers, include these polyfills:\n\n```html\n\n\n```\n\n Built with โค๏ธ and TypeScript\n
\n","readmeFilename":"README.md","_rev":"1-ac9a86d89fa0031eea056781df735f05"}