@pixelfiddler/core 0.1.7 → 1.0.1

package/README.md

@@ -15,22 +15,23 @@ yarn add @pixelfiddler/core
 ## Usage
 
 ```typescript
-import { buildTransformationUrl, buildQueryParams } from '@pixelfiddler/core';
+import { buildTransformationUrl, buildTransformationQueryParams } from '@pixelfiddler/core';
 
 // Build a complete transformation URL
-const url = buildTransformationUrl(
-  { baseUrl: 'https://example-media.com/images/photo.jpg' },
-  {
+const url = buildTransformationUrl({
+  src: '/images/photo.jpg',
+  baseUrl: 'https://cdn.example.com',
+  transformations: {
     width: 800,
     height: 600,
-    format: 'webp',
+    format: 'WEBP',
     quality: 85,
   }
-);
-// => 'https://example-media.com/images/photo.jpg?w=800&h=600&f=webp&q=85'
+});
+// => 'https://cdn.example.com/images/photo.jpg?w=800&h=600&f=WEBP&q=85'
 
 // Or just get the query string
-const params = buildQueryParams({
+const params = buildTransformationQueryParams({
   width: 400,
   blur: 5,
   grayscale: true,
@@ -40,25 +41,83 @@ const params = buildQueryParams({
 
 ## API
 
-### `buildTransformationUrl(config, options, mode?)`
+### `buildTransformationUrl(config)`
 
 Builds a complete transformation URL.
 
+```typescript
+buildTransformationUrl({
+  src: '/photo.jpg',
+  baseUrl: 'https://cdn.example.com',
+  transformations: { width: 800, format: 'WEBP' },
+  mode: 'short' // optional, default: 'short'
+});
+```
+
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `config` | `UrlBuilderConfig` | Configuration with `baseUrl` |
-| `options` | `TransformationOptions` | Transformation options |
+| `src` | `string` | Relative or absolute path to the image |
+| `baseUrl` | `string` | Base URL endpoint from PixelFiddler Dashboard |
+| `transformations` | `TransformationOptions` | Transformation options |
 | `mode` | `'short' \| 'long'` | Parameter naming mode (default: `'short'`) |
 
-### `buildQueryParams(options, mode?)`
+### `buildTransformationQueryParams(options, mode?)`
 
 Converts transformation options to a URL-encoded query string.
 
+```typescript
+buildTransformationQueryParams({ width: 800, format: 'WEBP' });
+// => 'w=800&f=WEBP'
+
+buildTransformationQueryParams({ width: 800 }, 'long');
+// => 'width=800'
+```
+
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `options` | `TransformationOptions` | Transformation options |
 | `mode` | `'short' \| 'long'` | Parameter naming mode (default: `'short'`) |
 
+### `createResponsiveAttributes(src, baseUrl?, options?)`
+
+Generates responsive image attributes (src, srcSet, sizes) for optimal loading.
+
+```typescript
+import { createResponsiveAttributes } from '@pixelfiddler/core';
+
+// Responsive image with sizes (uses `w` descriptors)
+createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
+  sizes: '(max-width: 768px) 100vw, 50vw',
+  transformations: { format: 'WEBP' }
+});
+// => {
+//   src: '...?w=3840&f=WEBP',
+//   srcSet: '...?w=640&f=WEBP 640w, ...?w=1024&f=WEBP 1024w, ...',
+//   sizes: '(max-width: 768px) 100vw, 50vw'
+// }
+
+// Fixed-width image (uses `x` descriptors for DPR)
+createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
+  width: 400
+});
+// => {
+//   src: '...?w=384',
+//   srcSet: '...?w=384 1x, ...?w=828 2x',
+//   width: 400
+// }
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `src` | `string` | Relative or absolute path to the image |
+| `baseUrl` | `string` | Base URL endpoint from PixelFiddler Dashboard |
+| `options.sizes` | `string` | Sizes attribute for responsive layouts |
+| `options.width` | `number` | Fixed display width (generates DPR variants) |
+| `options.deviceBreakpoints` | `number[]` | Custom device breakpoints |
+| `options.imageBreakpoints` | `number[]` | Custom image breakpoints |
+| `options.transformations` | `TransformationOptions` | Base transformations to apply |
+| `options.maxDpr` | `number` | Maximum DPR to support (default: 2) |
+
 ## Transformation Options
 
 ### Resize
@@ -68,7 +127,7 @@ Converts transformation options to a URL-encoded query string.
   width: 800,           // Target width (px)
   height: 600,          // Target height (px)
   dpr: 2,               // Device pixel ratio (1-4)
-  mode: 'FIT',          // 'FILL' | 'FIT' | 'PAD' | 'FORCE' | 'COVER'
+  mode: 'FIT',          // 'FILL' | 'FIT' | 'PAD'
   background: '#ffffff' // Background color for PAD mode
 }
 ```
@@ -77,7 +136,7 @@ Converts transformation options to a URL-encoded query string.
 
 ```typescript
 {
-  format: 'webp',       // 'jpg' | 'png' | 'webp' | 'avif' | 'gif' | 'auto'
+  format: 'WEBP',       // 'JPG' | 'PNG' | 'WEBP' | 'AVIF' | 'GIF'
   quality: 80,          // 1-100
   stripMetadata: true   // Remove EXIF data
 }
@@ -106,7 +165,7 @@ Converts transformation options to a URL-encoded query string.
   border: {
     width: 2,           // Border width (px)
     color: '#000000',   // Border color
-    radius: 8           // Corner radius (px)
+    radius: 8           // Corner radius (px, 1-2000)
   }
 }
 ```
@@ -114,20 +173,42 @@ Converts transformation options to a URL-encoded query string.
 ### Crop
 
 ```typescript
+// Simple crop with auto focus
 {
   crop: {
-    type: 'SIMPLE',           // 'SIMPLE' | 'OBJECT'
-    objectType: 'FACE',       // 'FACE' | 'UPPER_BODY' (for OBJECT type)
+    type: 'SIMPLE',
     width: 400,
     height: 300,
     focus: {
-      type: 'AUTO',           // 'SPECIFIED' | 'AUTO'
-      strategy: 'SMART',      // 'CENTER' | 'SMART' | 'DETAIL'
-      position: { x: 50, y: 50 }  // For SPECIFIED type
+      type: 'AUTO',
+      strategy: 'SMART'     // 'CENTER' | 'SMART' | 'DETAIL'
     },
     afterResize: true
   }
 }
+
+// Simple crop with specified position
+{
+  crop: {
+    type: 'SIMPLE',
+    width: 400,
+    height: 300,
+    focus: {
+      type: 'SPECIFIED',
+      position: { x: 50, y: 50 }
+    }
+  }
+}
+
+// Object detection crop
+{
+  crop: {
+    type: 'OBJECT',
+    objectType: 'FACE',     // 'FACE' | 'UPPER_BODY'
+    width: 400,
+    height: 300
+  }
+}
 ```
 
 ### Text Overlay
@@ -137,11 +218,11 @@ Converts transformation options to a URL-encoded query string.
   text: {
     text: 'Hello World',
     color: '#ffffff',
-    opacity: 80,
-    size: 50,
+    opacity: 80,            // 0-100
+    size: 50,               // Size as percentage (1-100)
     font: 'Arial',
-    fontSize: 24,
-    position: 'CENTER',
+    fontSize: 24,           // Font size in pixels
+    position: 'CENTER',     // Position constant
     background: '#000000',
     backgroundOpacity: 50
   }
@@ -163,6 +244,17 @@ Converts transformation options to a URL-encoded query string.
 }
 ```
 
+### Position Values
+
+For `text.position` and `watermark.position`:
+
+```
+'TOP_LEFT' | 'TOP' | 'TOP_RIGHT' |
+'LEFT' | 'CENTER' | 'RIGHT' |
+'BOTTOM_LEFT' | 'BOTTOM' | 'BOTTOM_RIGHT' |
+'AUTO'
+```
+
 ### Special Options
 
 ```typescript
@@ -188,7 +280,7 @@ By default, short parameter names are used for smaller URLs:
 Use `mode: 'long'` for full parameter names:
 
 ```typescript
-buildQueryParams({ width: 800 }, 'long');
+buildTransformationQueryParams({ width: 800 }, 'long');
 // => 'width=800'
 ```
 
@@ -198,12 +290,43 @@ Full TypeScript support with exported types:
 
 ```typescript
 import type {
+  // Main options
   TransformationOptions,
+  PixelFiddlerConfig,
+  UrlBuilderConfig,
+  BuildTransformationConfig,
+
+  // Resize
   ResizeOptions,
+  ResizeMode,
+  DevicePixelRatio,
+
+  // Format
+  FormatOptions,
+  ImageFormat,
+
+  // Effects
+  EffectOptions,
+  RotationAngle,
+
+  // Border
+  BorderOptions,
+  HexColor,
+
+  // Crop
   CropOptions,
+  SimpleCropOptions,
+  ObjectCropOptions,
+  CropFocusOptions,
+  CropType,
+  CropFocus,
+  CropFocusStrategy,
+  CropObjectType,
+
+  // Overlays
   TextOptions,
   WatermarkOptions,
-  UrlBuilderConfig,
+  Position,
 } from '@pixelfiddler/core';
 ```
 

package/dist/index.d.cts

@@ -79,7 +79,7 @@ type ObjectValue<T> = T[keyof T];
 /**
  * Resize mode for image transformations
  */
-type ResizeMode = 'FILL' | 'FIT' | 'PAD' | 'FORCE' | 'COVER';
+type ResizeMode = 'FILL' | 'FIT' | 'PAD';
 /**
  * Output image format - null or empty means AUTO
  */

package/dist/index.d.ts

@@ -79,7 +79,7 @@ type ObjectValue<T> = T[keyof T];
 /**
  * Resize mode for image transformations
  */
-type ResizeMode = 'FILL' | 'FIT' | 'PAD' | 'FORCE' | 'COVER';
+type ResizeMode = 'FILL' | 'FIT' | 'PAD';
 /**
  * Output image format - null or empty means AUTO
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelfiddler/core",
-  "version": "0.1.7",
+  "version": "1.0.1",
   "description": "Core utilities for PixelFiddler image transformation SDK",
   "type": "module",
   "main": "./dist/index.cjs",