@pixelfiddler/next 0.1.2 → 1.0.1

package/README.md

@@ -1 +1,239 @@
-TBD
+# @pixelfiddler/next
+
+Next.js image component for [PixelFiddler](https://pixel-fiddler.com) image transformations. A drop-in wrapper around `next/image` with automatic optimization through PixelFiddler CDN.
+
+## Installation
+
+```bash
+npm install @pixelfiddler/next
+# or
+pnpm add @pixelfiddler/next
+# or
+yarn add @pixelfiddler/next
+```
+
+**Note:** This package requires `next` >= 13.0.0 and `react` >= 18.2.0 as peer dependencies.
+
+## Quick Start
+
+```tsx
+import { PixelFiddlerImage } from '@pixelfiddler/next';
+
+function App() {
+  return (
+    <PixelFiddlerImage
+      src="https://example.com/photo.jpg"
+      alt="A beautiful photo"
+      width={800}
+      height={600}
+      transformations={{ format: 'WEBP', quality: 80 }}
+    />
+  );
+}
+```
+
+## Components
+
+### `PixelFiddlerImage`
+
+A wrapper around Next.js `Image` component that uses PixelFiddler as the image loader for automatic optimization.
+
+```tsx
+import { PixelFiddlerImage } from '@pixelfiddler/next';
+
+// Basic usage with dimensions
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Profile photo"
+  width={400}
+  height={300}
+/>
+
+// Fill container
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Hero image"
+  fill
+  sizes="(max-width: 768px) 100vw, 50vw"
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | **required** | URL of the image (relative or absolute). Relative paths are attached to `baseUrl` |
+| `baseUrl` | `string` | - | Base URL endpoint from PixelFiddler Dashboard. Can be set via `PixelFiddlerProvider` |
+| `sizes` | `string` | - | Sizes attribute for responsive images (e.g., `"(max-width: 768px) 100vw, 50vw"`) |
+| `responsive` | `boolean` | `true` | Enable automatic srcset generation via PixelFiddler loader |
+| `transformations` | `TransformationOptions` | - | Image transformation options |
+
+All standard Next.js `Image` props (`width`, `height`, `fill`, `quality`, `priority`, `placeholder`, `unoptimized`, `className`, etc.) are also supported.
+
+### `PixelFiddlerProvider`
+
+A context provider for sharing configuration across all `PixelFiddlerImage` components.
+
+```tsx
+import { PixelFiddlerProvider, PixelFiddlerImage } from '@pixelfiddler/next';
+
+function App() {
+  return (
+    <PixelFiddlerProvider config={{ baseUrl: 'https://cdn.example.com' }}>
+      <PixelFiddlerImage src="/photos/hero.jpg" alt="Hero" fill sizes="100vw" />
+      <PixelFiddlerImage src="/photos/thumb.jpg" alt="Thumbnail" width={200} height={200} />
+    </PixelFiddlerProvider>
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `PixelFiddlerConfig` | Configuration object with `baseUrl` and optional `maxDpr` |
+| `children` | `ReactNode` | Child components |
+
+## Usage Examples
+
+### Basic Transformations
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Transformed image"
+  width={800}
+  height={600}
+  transformations={{
+    format: 'WEBP',
+    quality: 85,
+    blur: 10,
+  }}
+/>
+```
+
+### Fill Container
+
+Use `fill` prop for images that should fill their parent container:
+
+```tsx
+<div style={{ position: 'relative', width: '100%', height: '400px' }}>
+  <PixelFiddlerImage
+    src="https://example.com/hero.jpg"
+    alt="Hero banner"
+    fill
+    sizes="100vw"
+    style={{ objectFit: 'cover' }}
+    transformations={{ format: 'WEBP' }}
+  />
+</div>
+```
+
+### Priority Loading
+
+For above-the-fold images, use `priority` to preload:
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority
+  transformations={{ format: 'WEBP' }}
+/>
+```
+
+### Disable Responsive Behavior
+
+When `responsive` is false, the image URL is built with exact transformations and no srcset is generated:
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Non-responsive"
+  width={400}
+  height={300}
+  responsive={false}
+  transformations={{ width: 400, height: 300, format: 'WEBP' }}
+/>
+```
+
+### Unoptimized Images
+
+Skip the PixelFiddler loader entirely:
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Unoptimized"
+  width={400}
+  height={300}
+  unoptimized
+/>
+```
+
+### With Quality Override
+
+The `quality` prop is passed to transformations:
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="High quality"
+  width={800}
+  height={600}
+  quality={95}
+/>
+```
+
+### Responsive Sizes
+
+```tsx
+<PixelFiddlerImage
+  src="https://example.com/photo.jpg"
+  alt="Responsive image"
+  fill
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
+  transformations={{ format: 'WEBP' }}
+/>
+```
+
+## How It Works
+
+The component uses a custom Next.js image loader that:
+
+1. Receives width requests from Next.js's responsive image system
+2. Builds PixelFiddler transformation URLs with the requested width
+3. Applies any additional transformations you specify
+
+This means Next.js handles the responsive `srcset` generation while PixelFiddler handles the actual image transformations and delivery.
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  PixelFiddlerImageProps,
+  PixelFiddlerContextValue,
+  TransformationOptions,
+  ResizeOptions,
+  FormatOptions,
+  EffectOptions,
+  CropOptions,
+  BorderOptions,
+  TextOptions,
+  WatermarkOptions,
+  PixelFiddlerConfig,
+} from '@pixelfiddler/next';
+```
+
+## Related
+
+- [@pixelfiddler/core](https://www.npmjs.com/package/@pixelfiddler/core) - Core utilities for building transformation URLs
+- [@pixelfiddler/react](https://www.npmjs.com/package/@pixelfiddler/react) - React components for non-Next.js projects
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelfiddler/next",
-  "version": "0.1.2",
+  "version": "1.0.1",
   "description": "Next.js image component and loader for PixelFiddler image transformation SDK",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,11 +22,11 @@
     "dist"
   ],
   "dependencies": {
-    "@pixelfiddler/core": "0.1.7"
+    "@pixelfiddler/core": "1.0.0"
   },
   "peerDependencies": {
     "next": ">=13.0.0",
-    "react": ">=18.0.0"
+    "react": ">=18.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",