{"_id":"@7haven/h-image","_rev":"13-13e61922e4b695b193dfa33a6215dbae","name":"@7haven/h-image","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@7haven/h-image","version":"1.1.0","keywords":["svelte","svelte5","image","avif","webp","optimization","responsive","performance","cdn","cloudflare","picture","srcset"],"author":{"name":"7Haven"},"license":"MIT","_id":"@7haven/h-image@1.1.0","maintainers":[{"name":"nigeltee","email":"nigelnyakudya@gmail.com"}],"homepage":"https://github.com/7haveeen/h-image#readme","bugs":{"url":"https://github.com/7haveeen/h-image/issues"},"dist":{"shasum":"732629ebdb5f9c55a11ff541e43543cc98403fc0","tarball":"https://registry.npmjs.org/@7haven/h-image/-/h-image-1.1.0.tgz","fileCount":24,"integrity":"sha512-exWa/F9y+0qggYhCNoVqwe14wwKUKxy6idn0K+I4kI4O6aOb/YJYdLzuDX3VVTqT8uw9yHSfSpCO3Ku1EVdZSw==","signatures":[{"sig":"MEYCIQDhXoBWlw6+Okw62l4+JQhr2srg/hQ4bCjEMTaUlcguTAIhAKFeYfMMWmgDa8lvp1dDML0Ziezg0vqFdfbxyZXhvxpW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37677},"type":"module","svelte":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","svelte":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"467ff4ea4ecb4fe828c1929a2a4995f62d44eee7","scripts":{"test":"vitest run","build":"npm run generate-version && svelte-package","pretest":"npm run generate-version","typecheck":"tsc --noEmit --skipLibCheck","test:watch":"vitest","prepublishOnly":"npm run build && npm run typecheck","generate-version":"node scripts/generate-version.js"},"_npmUser":{"name":"nigeltee","email":"nigelnyakudya@gmail.com"},"repository":{"url":"git+https://github.com/7haveeen/h-image.git","type":"git"},"_npmVersion":"11.4.1","description":"Production-ready Svelte 5 image component with automatic AVIF/WebP optimization, zero layout shift, and type-safe API","directories":{},"sideEffects":false,"_nodeVersion":"23.10.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jsdom":"^27.1.0","svelte":"5.43.3","vitest":"4.0.6","typescript":"^5.9.3","@vitest/browser":"^4.0.6","@sveltejs/package":"^2.5.4","@testing-library/svelte":"^5.2.8","@sveltejs/vite-plugin-svelte":"^6.2.1"},"peerDependencies":{"svelte":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/h-image_1.1.0_1762276157299_0.10059955087864281","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@7haven/h-image","type":"module","version":"1.1.1","description":"Production-ready Svelte 5 image component with automatic AVIF/WebP optimization, zero layout shift, and type-safe API","author":{"name":"7Haven"},"license":"MIT","homepage":"https://github.com/7haveeen/h-image#readme","repository":{"type":"git","url":"git+https://github.com/7haveeen/h-image.git"},"bugs":{"url":"https://github.com/7haveeen/h-image/issues"},"keywords":["svelte","svelte5","image","avif","webp","optimization","responsive","performance","cdn","cloudflare","picture","srcset"],"sideEffects":false,"svelte":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","svelte":"./dist/index.js","default":"./dist/index.js"}},"engines":{"node":">=18.0.0"},"scripts":{"generate-version":"node scripts/generate-version.js","build":"npm run generate-version && svelte-package","pretest":"npm run generate-version","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit --skipLibCheck","prepublishOnly":"npm run build && npm run typecheck"},"peerDependencies":{"svelte":"^5.0.0"},"devDependencies":{"@sveltejs/package":"^2.5.4","@sveltejs/vite-plugin-svelte":"^6.2.1","@testing-library/svelte":"^5.2.8","@vitest/browser":"^4.0.6","jsdom":"^27.1.0","svelte":"5.43.3","typescript":"^5.9.3","vitest":"4.0.6"},"publishConfig":{"access":"public"},"_id":"@7haven/h-image@1.1.1","gitHead":"25380d4c36d472c10dafec3e8cb8c28f2d648cc9","_nodeVersion":"23.10.0","_npmVersion":"11.4.1","dist":{"integrity":"sha512-PJSdq24hGtmGPc1lY6FMK0gbPYcPN0cnsn07Z7+jfkl1cgUhkNSK1IL7vF7r2NTAsKMmuRpBGRS6jTxYjxJuQg==","shasum":"d3cd062d8a65009283fea21efcd55801d7342995","tarball":"https://registry.npmjs.org/@7haven/h-image/-/h-image-1.1.1.tgz","fileCount":24,"unpackedSize":37527,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDielQn6LL12JwQgfjZ/7pzK/98v/pUYKwrB3c6uOYLWgIhAKfmv7d/DJsPzkHJiqZMbtNichqJaUSkl+e3r1zUIcN+"}]},"_npmUser":{"name":"nigeltee","email":"nigelnyakudya@gmail.com"},"directories":{},"maintainers":[{"name":"nigeltee","email":"nigelnyakudya@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/h-image_1.1.1_1763043290504_0.999977206185622"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-04T17:09:17.177Z","modified":"2025-11-13T14:14:50.896Z","1.0.0":"2025-11-04T10:41:04.279Z","1.0.1":"2025-11-04T14:12:20.192Z","1.0.2":"2025-11-04T15:23:22.611Z","1.0.3":"2025-11-04T15:55:16.478Z","1.0.4":"2025-11-04T16:28:43.982Z","1.1.0":"2025-11-04T17:09:17.525Z","1.1.1":"2025-11-13T14:14:50.713Z"},"bugs":{"url":"https://github.com/7haveeen/h-image/issues"},"author":{"name":"7Haven"},"license":"MIT","homepage":"https://github.com/7haveeen/h-image#readme","keywords":["svelte","svelte5","image","avif","webp","optimization","responsive","performance","cdn","cloudflare","picture","srcset"],"repository":{"type":"git","url":"git+https://github.com/7haveeen/h-image.git"},"description":"Production-ready Svelte 5 image component with automatic AVIF/WebP optimization, zero layout shift, and type-safe API","maintainers":[{"name":"nigeltee","email":"nigelnyakudya@gmail.com"}],"readme":"<div align=\"center\">\n  <h1>@7haven/h-image</h1>\n  <p>Production-ready Svelte 5 image component with automatic AVIF → WebP → fallback optimization</p>\n  \n  [![npm version](https://img.shields.io/npm/v/@7haven/h-image?color=blue)](https://www.npmjs.com/package/@7haven/h-image)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n  [![Svelte 5](https://img.shields.io/badge/Svelte-5-orange.svg)](https://svelte.dev/)\n  \n  <p>\n    <strong>Type-safe • Zero Dependencies • Zero Layout Shift • CDN-Ready</strong>\n  </p>\n</div>\n\n---\n\n## ✨ Features\n\n- 🚀 **Auto-optimized** — AVIF → WebP → fallback format selection (30-50% smaller)\n- 🎯 **Zero CLS** — Prevents layout shift with aspect ratio\n- 📘 **Type-safe** — Full TypeScript support with strict types\n- ⚡ **Modern** — Svelte 5 runes (`$state`, `$derived`, `$effect`)\n- 📱 **Responsive** — Automatic srcset with configurable DPR support\n- 🌐 **CDN-ready** — Works with Cloudflare, Imgix, or any image CDN\n- 🪶 **Lightweight** — Zero runtime dependencies, tree-shakeable\n- ✅ **Production-tested** — 55 unit tests, 100% type coverage\n- 🔒 **Secure** — XSS-safe with strict input validation\n\n## 📦 Installation\n\n```bash\nnpm install @7haven/h-image\n```\n\n<details>\n<summary>Other package managers</summary>\n\n```bash\n# Yarn\nyarn add @7haven/h-image\n\n# pnpm\npnpm add @7haven/h-image\n\n# Bun\nbun add @7haven/h-image\n```\n\n</details>\n\n## 🚀 Quick Start\n\n```svelte\n<script>\n\timport { Image, configureCdn } from '@7haven/h-image';\n\n\t// Optional: Configure your CDN\n\tconfigureCdn({ baseUrl: 'https://cdn.example.com' });\n</script>\n\n<!-- Auto-optimized: AVIF → WebP → fallback -->\n<Image src=\"file/hero\" alt=\"Hero image\" width={1200} aspectRatio=\"21/9\" />\n```\n\nThat's it! The component automatically:\n\n- ✅ Generates AVIF and WebP versions\n- ✅ Creates responsive srcset\n- ✅ Prevents layout shift\n- ✅ Lazy loads by default\n\n## 📖 Usage Examples\n\n### Hero Image (LCP Optimization)\n\n```svelte\n<Image\n\tsrc=\"file/hero\"\n\talt=\"Hero banner\"\n\twidth={1920}\n\taspectRatio=\"21/9\"\n\tfetchpriority=\"high\"\n\tloading=\"eager\"\n/>\n```\n\n### Product Grid\n\n```svelte\n<Image\n\tsrc=\"file/product\"\n\talt=\"Product thumbnail\"\n\twidth={400}\n\taspectRatio=\"1/1\"\n\ttransform={{ quality: 85 }}\n/>\n```\n\n### Art Direction\n\nDifferent images for different screen sizes:\n\n```svelte\n<Image\n\tsrc=\"file/fallback\"\n\talt=\"Responsive hero\"\n\twidth={1200}\n\tsources={[\n\t\t{ src: 'file/desktop-wide', media: '(min-width: 768px)' },\n\t\t{ src: 'file/mobile-square', media: '(max-width: 767px)' }\n\t]}\n/>\n```\n\n### Image Transforms\n\n```svelte\n<Image\n\tsrc=\"file/photo\"\n\talt=\"Enhanced photo\"\n\twidth={800}\n\ttransform={{\n\t\tblur: 10,\n\t\tbrightness: 1.2,\n\t\tquality: 90\n\t}}\n/>\n```\n\n## ⚙️ Props\n\n| Prop            | Type                             | Default      | Description                          |\n| --------------- | -------------------------------- | ------------ | ------------------------------------ |\n| `src`           | `string`                         | **required** | Image source (CDN path or URL)       |\n| `alt`           | `string`                         | **required** | Alt text for accessibility           |\n| `width`         | `number`                         | -            | Display width in pixels              |\n| `height`        | `number`                         | -            | Display height in pixels             |\n| `aspectRatio`   | `string \\| number`               | -            | Aspect ratio (e.g., `\"16/9\"`, `1.5`) |\n| `modernFormats` | `boolean`                        | `true`       | Auto-generate AVIF/WebP sources      |\n| `sources`       | `ImageSource[]`                  | -            | Custom sources for art direction     |\n| `transform`     | `TransformOptions`               | `{}`         | CDN transformation options           |\n| `loading`       | `'lazy' \\| 'eager'`              | `'lazy'`     | Loading strategy                     |\n| `fetchpriority` | `'high' \\| 'low' \\| 'auto'`      | -            | Resource priority hint               |\n| `placeholder`   | `'blur' \\| 'none' \\| string`     | `'blur'`     | Placeholder while loading            |\n| `fit`           | `'cover' \\| 'contain' \\| 'fill'` | -            | Object-fit behavior                  |\n| `position`      | `string`                         | `'center'`   | Object-position value                |\n| `sizes`         | `string`                         | auto         | Custom sizes attribute               |\n| `class`         | `string`                         | -            | Additional CSS classes               |\n\n## 🎨 Advanced Usage\n\n### Custom Sizes Attribute\n\n```svelte\n<Image src=\"file/hero\" alt=\"Hero\" width={1200} sizes=\"(min-width: 1024px) 50vw, 100vw\" />\n```\n\n### Object Fit & Position\n\n```svelte\n<Image\n\tsrc=\"file/portrait\"\n\talt=\"Person\"\n\twidth={400}\n\theight={400}\n\tfit=\"cover\"\n\tposition=\"top center\"\n/>\n```\n\n### Disable Modern Formats\n\n```svelte\n<Image src=\"file/legacy\" alt=\"Legacy browser support\" width={800} modernFormats={false} />\n```\n\n### Custom Placeholder\n\n```svelte\n<Image src=\"file/hero\" alt=\"Hero\" width={1200} placeholder=\"data:image/svg+xml,...\" />\n```\n\n## 💡 Best Practices\n\n### Performance\n\n- ✅ Always provide `width` + `height` **OR** `aspectRatio` to prevent CLS\n- ✅ Use `fetchpriority=\"high\"` + `loading=\"eager\"` for LCP images **only**\n- ✅ Keep `modernFormats={true}` (default) for 30-50% smaller file sizes\n- ✅ Customize `sizes` attribute for responsive layouts\n- ✅ Use `quality: 85` for optimal size/quality balance\n- ✅ Component uses CSS `contain` for rendering performance\n\n### Security\n\n- 🔒 XSS-safe URL construction (native `URL` API)\n- 🔒 Strict input validation on all parameters\n- 🔒 EXIF metadata automatically stripped by CDN\n- 🔒 No script injection vulnerabilities\n- 🔒 Type-safe props prevent invalid configurations\n\n### Accessibility\n\n- ♿ `alt` text is **required** (TypeScript enforced)\n- ♿ Semantic HTML (`<picture>`, `<img>`)\n- ♿ Native keyboard navigation support\n- ♿ Screen reader friendly\n- ♿ ARIA roles supported via `role` prop\n\n## 🔧 Configuration\n\n### CDN Setup\n\n```typescript\nimport { configureCdn } from '@7haven/h-image';\n\n// Configure once in your root layout\nconfigureCdn({\n\tbaseUrl: 'https://cdn.example.com'\n});\n```\n\n### Available Transforms\n\n| Transform    | Type                             | Description       |\n| ------------ | -------------------------------- | ----------------- |\n| `format`     | `'avif' \\| 'webp' \\| 'auto'`     | Output format     |\n| `width`      | `number`                         | Resize width      |\n| `height`     | `number`                         | Resize height     |\n| `fit`        | `'cover' \\| 'contain' \\| 'fill'` | Resize behavior   |\n| `quality`    | `number` (1-100)                 | Image quality     |\n| `blur`       | `number`                         | Blur intensity    |\n| `sharpen`    | `number`                         | Sharpen intensity |\n| `brightness` | `number`                         | Brightness level  |\n| `contrast`   | `number`                         | Contrast level    |\n| `saturation` | `number`                         | Saturation level  |\n| `rotate`     | `number`                         | Rotation degrees  |\n\n### Default Breakpoints\n\n```typescript\n[400, 800, 1200, 1600] + // Standard\n\t2048; // When zoom={true}\n```\n\n## 📚 API Reference\n\n### Components\n\n```typescript\nimport { Image } from '@7haven/h-image';\n```\n\n### Configuration\n\n```typescript\nimport { configureCdn, getCdnConfig } from '@7haven/h-image';\n\n// Configure CDN\nconfigureCdn({ baseUrl: 'https://cdn.example.com' });\n\n// Get current config\nconst config = getCdnConfig();\n```\n\n### Utilities\n\n```typescript\nimport {\n\tbuildImageUrl, // Build CDN URL\n\tgenerateSrcset, // Generate srcset string\n\tgenerateSizes, // Generate sizes attribute\n\tcalculateHeight, // Calculate height from aspect ratio\n\tgenerateBlurPlaceholder // Generate blur placeholder\n} from '@7haven/h-image';\n```\n\n### Version\n\n```typescript\nimport { COMPONENT_VERSION } from '@7haven/h-image';\n\nconsole.log(COMPONENT_VERSION); // '1.0.0'\n```\n\n### TypeScript Types\n\n```typescript\nimport type {\n\tImageProps, // Component props\n\tImageSource, // Source object for art direction\n\tTransformOptions, // CDN transform options\n\tImageFormat, // 'avif' | 'webp' | 'auto'\n\tFetchPriority, // 'high' | 'low' | 'auto'\n\tPlaceholderType, // 'blur' | 'none'\n\tCdnConfig // CDN configuration\n} from '@7haven/h-image';\n```\n\n## 🌐 CDN Compatibility\n\nWorks with any CDN that supports image transformations via query parameters:\n\n- ✅ **Cloudflare R2** with [Image Resizing](https://developers.cloudflare.com/images/)\n- ✅ **Imgix**\n- ✅ **Cloudinary**\n- ✅ **Vercel Image Optimization**\n- ✅ **Custom CDN** (as long as it supports query params)\n\n```typescript\n// Example: Cloudflare R2\nconfigureCdn({ baseUrl: 'https://cdn.7haven.online' });\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. 🐛 **Report bugs** — Open an issue with reproduction steps\n2. 💡 **Suggest features** — Share your ideas for improvements\n3. 🔧 **Submit PRs** — Fix bugs or add features\n4. 📖 **Improve docs** — Help make documentation clearer\n\n## 📄 License\n\nMIT © [7Haven](https://github.com/7haven)\n\n## 🙏 Acknowledgments\n\nBuilt with:\n\n- [Svelte 5](https://svelte.dev/) — The reactive framework\n- [TypeScript](https://www.typescriptlang.org/) — Type safety\n- [Vitest](https://vitest.dev/) — Testing framework\n\n---\n\n<div align=\"center\">\n  <sub>Made with ❤️ by 7Haven</sub>\n</div>\n","readmeFilename":"README.md"}