img-upload-kit 0.0.0-stage → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `img-upload-kit` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-10-31
+
+### Added
+
+- **AnimatedImage Component (`img-upload-kit/react`)**:
+  - High-performance progressive blur-up display component with GPU-accelerated crossfade.
+  - Native `<img>` attribute pass-through and framework-agnostic `as` prop (e.g. `as={Image}` for Next.js with `imageComponentProps`).
+  - Hierarchical placeholder fallback cascade: `blurDataUrl` (LQIP) > `blurHash` (client canvas decode) > `blurColor` (gradient SVG).
+  - Shimmer highlight animation (`showShimmer`), staggered transition timing, and full `prefers-reduced-motion` compliance.
+  - Semantic slot targeting (`data-slot`, `data-state`, `aria-busy`) and unstyled mode support.
+- **Headless Reveal State Machine (`useImageReveal`)**:
+  - Headless hook managing progressive reveal states (`isLoaded`, `showPlaceholder`, `hasError`, `imgRef`, `handleLoad`, `handleError`).
+  - Guarantees pre-decode verification via `HTMLImageElement.decode()` before revealing sharp asset.
+  - Synchronous reset on `srcKey` changes and automatic detection of pre-cached images.
+- **Placeholder Utilities**:
+  - `createFallbackBlurSvg`: Generates lightweight inline SVG gradients derived from dominant color.
+  - `resolveMeaningfulColor`: Filters out generic neutral/black/white database defaults and validates color tokens.
+  - `resolvePlaceholderUrl`: Deterministically selects the best available placeholder asset.
+
+### Changed & Hardened
+
+- **Server Validation Error Mapping**:
+  - Updated `createUploadHttpHandler.POST` to map client validation errors (file size limits, unsupported MIME types, missing file payloads) directly to HTTP 400 Bad Request instead of internal server errors.
+- **Collision Retry Discrimination**:
+  - Fixed collision detection in `uploadRetry.ts` to strictly match `already exists` and `EEXIST` error codes without falsely triggering on `does not exist` messages.
+- **Sharp Mobile EXIF Auto-Rotation**:
+  - Added `.rotate()` during Sharp pipeline initialization in `imageOptimizer.ts` to automatically orient smartphone and digital camera uploads according to EXIF orientation metadata.
+- **Transparent PNG Color Extraction**:
+  - Hardened `colorHistogram.ts` to ignore pixels with `alpha < 8`, preventing transparent PNG graphics from skewing dominant edge colors toward black or white.
+- **BlurHash & SVG Detection**:
+  - Enhanced SVG validation in `blurGenerator.ts` to perform case-insensitive checks across the initial 1024 bytes and clamped BlurHash components to valid ranges (1–9).
+- **Storage Parity & Upsert Semantics**:
+  - Implemented `deleteByUrl` in `createLocalFsStorageAdapter` for parity with cloud storage providers.
+  - Aligned default `upsert` semantics to `true` across all adapters for consistent overwrite behavior.
+- **React Pure State Updaters & Controlled Value Sync**:
+  - Refactored `useMultiImageState.ts` and `useSingleImageState.ts` to maintain synchronous `previewsRef` snapshots.
+  - Removed side-effect dispatches (`emitImmediateChange`) from inside `setPreviews` functional updaters for strict React 18/19 concurrent rendering purity.
+  - Properly reset uploaded data and blur previews when single uploader `value` transitions to `null`.
+- **Batch Preemption Clearing in Multi-Upload**:
+  - Fixed retention window in `MultiImageUpload.tsx`: active batch references are now explicitly cleared when an in-flight retention timer is preempted by a new upload batch.
+
+## [1.0.0] - 2026-10-31
+
+### Added
+
+- **Core Types & Utilities (`img-upload-kit`)**:
+  - Universal project-agnostic visual role presets (`thumbnail`, `avatar`, `card`, `cover`, `hero`, `logo`, `original`).
+  - `defineUploadPresets` helper and `UploadKitRegister` TypeScript module augmentation for global preset autocomplete.
+  - Bilingual (`en` / `ar`) file validation, quality level presets, byte formatters, and RGB/HEX color utilities.
+- **Server Optimization & Upload Pipeline (`img-upload-kit/server`)**:
+  - `createImageUploader` with preset inheritance, path sanitization, SHA-256 content hashing, retry handling, and `AsyncSemaphore` concurrency control.
+  - `createUploadHttpHandler` returning Web Standard `POST` and `DELETE` Fetch handlers (`Request` -> `Response`) compatible with Next.js App Router, Remix, React Router, Hono, SvelteKit, and Node servers.
+  - `optimizeImage` powered by Sharp with smart AVIF size-guarding (preventing file bloat on pre-compressed JPEGs), WebP fallback, and SVG passthrough.
+  - `generateBlurPlaceholder` generating compact WebP LQIP data URLs, optional BlurHash strings, and 4-edge weighted dominant color histograms.
+- **Pluggable Storage Adapters (`img-upload-kit/storage`)**:
+  - `StorageAdapter` contract and `createStorageAdapter` authoring helper.
+  - Built-in `createSupabaseStorageAdapter`, `createS3StorageAdapter` (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces), `createLocalFsStorageAdapter` (with path-traversal protection), and `createMemoryStorageAdapter`.
+  - `onUploadRecord` hook for persisting upload metadata to Prisma, Drizzle, or analytics pipelines.
+- **Blur Manifest Service (`img-upload-kit/blur`)**:
+  - `BlurService` and `createBlurService` with bounded `LRUCache`, normalized URL/path lookup, and SVG fallback placeholders.
+- **Pure React UI & Styles (`img-upload-kit/react`, `img-upload-kit/styles.css`)**:
+  - Framework-agnostic `<ImageUploadProvider>`, `<ImageUpload>`, `<SingleImageUpload>`, `<MultiImageUpload>`, `<BlurImage>`, and `<QualitySelector>`.
+  - First-class English & Arabic (`dir="rtl"`) localization, custom `renderImage` adapter slot, and themeable `--iuk-*` CSS custom properties.
+- **Headless Hooks & Primitives (`img-upload-kit/headless`)**:
+  - Unstyled controllers: `HeadlessSingleUpload`, `HeadlessMultiUpload`, `useSingleUpload`, `useMultiUpload`, `useImageUpload`, `useDropzone`, `useFilePreview`.
+- **Blur Manifest CLI (`img-upload-kit/cli`)**:
+  - `img-upload-kit` / `blur-cli` binaries (`generate`, `validate`, `sync`, `cleanup`, `health`, `inspect`) for build-time `blur-hashes.json` generation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mo Elsherbiny (https://www.buildwithsherbo.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# img-upload-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Production-grade, zero-lock-in image upload and processing framework with **Sharp AVIF/WebP optimization**, **smart size-guarding**, **WebP LQIP & BlurHash placeholders**, **4-edge dominant color extraction**, **pluggable storage adapters**, **4 styling tiers**, and the **`<AnimatedImage />` blur-up display component** for React & Next.js.
+
+[![Live Interactive Demo](https://img.shields.io/badge/Live%20Demo-upload--kit.buildwithsherbo.com-0284c7?style=for-the-badge)](https://upload-kit.buildwithsherbo.com)
+[![npm version](https://img.shields.io/npm/v/img-upload-kit?color=38bdf8&style=for-the-badge)](https://www.npmjs.com/package/img-upload-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](./LICENSE)
+[![Studio Repo](https://img.shields.io/badge/Studio%20Code-image--upload--kit--studio-1e293b?style=for-the-badge&logo=github)](https://github.com/MoElsherbiny/image-upload-kit-studio)
+
+---
+
+## Interactive Studio & Live Demo
+
+Experience the full pipeline live in your browser:
+
+👉 **[upload-kit.buildwithsherbo.com](https://upload-kit.buildwithsherbo.com)**
+
+- **Watch Code Stream Live**: Synchronized Shiki IDE writing `<AnimatedImage />`, upload route, and UI code while the live preview mutates at 60 FPS.
+- **4-Layer Placeholder Lab**: Side-by-side comparison of **4-Edge Ambient Color** (0 B runtime), **Client BlurHash** (~28 chars), **WebP LQIP Data URL** (<1 KB), and the final **Sharp AVIF/WebP** asset.
+- **Sharp Size-Guard Sandbox**: Drop any image to inspect real-time byte savings, dimensions, and color extraction.
+- **Studio Source Code**: Open source at [`MoElsherbiny/image-upload-kit-studio`](https://github.com/MoElsherbiny/image-upload-kit-studio).
+
+---
+
+## The Problems Solved
+
+1. **Pipeline Fragmentation**: Eliminates stitching separate libraries for file validation, resizing, AVIF/WebP conversion, placeholder generation, storage uploading, and UI forms. Provides one unified pipeline from browser dropzone to CDN.
+2. **AVIF Bloat on Pre-compressed JPEGs**: Naive AVIF converters expand pre-compressed inputs by 30–80%. Our **Sharp Size-Guard** evaluates output bytes against source size, scales quality proportionally, and falls back to WebP or passthrough.
+3. **Cumulative Layout Shift (CLS)**: Eliminates layout shifts by generating instant **WebP LQIP data URLs** (<8KB), client-decoded **BlurHash** strings, and **4-edge ambient colors** before full-resolution assets load.
+4. **Storage Vendor Lock-in**: Decouples application logic from cloud vendors via a uniform `StorageAdapter` contract across AWS S3, Cloudflare R2, Supabase, Local Filesystem, or In-Memory (testing).
+5. **UI Styling Lock-in**: Provides 4 styling tiers: default `--iuk-*` CSS tokens, `unstyled` mode with Tailwind/CSS Modules, partial slot renderers, or 100% headless hooks and primitives.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install img-upload-kit
+# pnpm
+pnpm add img-upload-kit
+# yarn
+yarn add img-upload-kit
+# bun
+bun add img-upload-kit
+
+# Optional peer dependencies (only if using React or Headless UI):
+npm install react react-dom
+```
+
+> **Requirements**: Node.js `>= 18.17.0` on the server for `sharp` and Web Fetch `Request`/`FormData` APIs. React `>= 18.0.0` for UI components.
+
+---
+
+## Subpath Exports Reference
+
+| Subpath | Environment | Key Exports |
+| --- | --- | --- |
+| `img-upload-kit` | Universal | `STANDARD_PRESETS`, `defineUploadPresets`, types, color utils, validators, `createMemoryStorageAdapter`, `decodeBlurHashToDataURL`, `getBlurData` |
+| `img-upload-kit/server` | Node.js | `createImageUploader`, `createUploadHttpHandler`, `optimizeImage`, `generateBlurPlaceholder` |
+| `img-upload-kit/storage` | Node / Edge | `createStorageAdapter`, `createS3StorageAdapter`, `createSupabaseStorageAdapter`, `createLocalFsStorageAdapter` |
+| `img-upload-kit/blur` | Universal | `BlurService`, `createBlurService`, `decodeBlurHashToDataURL`, `LRUCache` |
+| `img-upload-kit/react` | React Client | `<ImageUploadProvider>`, `<SingleImageUpload>`, `<MultiImageUpload>`, `<AnimatedImage>`, `<BlurImage>` |
+| `img-upload-kit/headless` | React Client | `<HeadlessSingleUpload>`, `<HeadlessMultiUpload>`, `useSingleUpload`, `useMultiUpload`, `useDropzone` |
+| `img-upload-kit/cli` | Node CLI | CLI binaries (`img-upload-kit` / `blur-cli`) for build-time manifest generation |
+| `img-upload-kit/styles.css` | CSS | Complete stylesheet powered by `--iuk-*` design tokens (supports dark mode & RTL) |
+
+---
+
+## Universal Presets Reference
+
+Built-in visual role presets balance dimension constraints, compression quality, and blur generation:
+
+| Preset | Max Dimensions | Max Size | Quality | Allowed Formats | Blur / Notes |
+| --- | --- | --- | --- | --- | --- |
+| `thumbnail` | `600x600` | 5 MB | Q78 | JPEG, PNG, WebP, AVIF | Medium quality, compact size |
+| `avatar` | `512x512` | 5 MB | Q80 | JPEG, PNG, WebP, AVIF | Medium quality, square profile |
+| `card` | `1200x900` | 8 MB | Q85 | JPEG, PNG, WebP, AVIF, SVG | High quality content cards |
+| `cover` | `1920x1080` | 10 MB | Q88 | JPEG, PNG, WebP, AVIF, SVG | High quality wide banners |
+| `hero` | `2560x1440` | 15 MB | Q92 | JPEG, PNG, WebP, AVIF, SVG | Maximum detail for hero headers |
+| `logo` | `800x800` | 5 MB | Q90 | JPEG, PNG, WebP, AVIF, SVG | Vector SVG passthrough & sharp edges |
+| `original` | `4096x4096` | 25 MB | Q95 | JPEG, PNG, WebP, AVIF, SVG | Preserves maximum master fidelity |
+
+```ts
+import { defineUploadPresets } from 'img-upload-kit';
+
+export const presets = defineUploadPresets({
+  'product-gallery': {
+    folder: 'catalog/products',
+    maxDimensions: { width: 1600, height: 1600 },
+    maxSizeMB: 10,
+    quality: 85,
+    includeBlurHash: true,
+  },
+});
+```
+
+---
+
+## Subpath Usage Guides
+
+### 1. Server Uploader & Route Handler (`/server` & `/storage`)
+
+```ts
+// app/api/upload/route.ts (Next.js App Router, Remix, Hono, SvelteKit)
+import { createImageUploader, createUploadHttpHandler } from 'img-upload-kit/server';
+import { createS3StorageAdapter } from 'img-upload-kit/storage';
+
+const storage = createS3StorageAdapter({
+  publicBaseUrl: 'https://cdn.example.com',
+  defaultBucket: 'media',
+  putObject: (input) => s3.send(new PutObjectCommand(input)),
+  deleteObject: (input) => s3.send(new DeleteObjectCommand(input)),
+});
+
+export const uploader = createImageUploader({ storage, defaultBucket: 'media' });
+export const { POST, DELETE } = createUploadHttpHandler({ uploader });
+```
+
+### 2. Client Provider & Upload UI (`/react` & `/styles.css`)
+
+```tsx
+import { useState } from 'react';
+import { ImageUploadProvider, SingleImageUpload, MultiImageUpload } from 'img-upload-kit/react';
+import type { UploadedImageData } from 'img-upload-kit';
+import 'img-upload-kit/styles.css';
+
+export function MediaForm() {
+  const [avatar, setAvatar] = useState<UploadedImageData | null>(null);
+  const [gallery, setGallery] = useState<UploadedImageData[]>([]);
+
+  return (
+    <ImageUploadProvider endpoint="/api/upload" locale="en">
+      <SingleImageUpload preset="avatar" label="Avatar" value={avatar} onChange={setAvatar} />
+      <MultiImageUpload preset="card" label="Gallery" value={gallery} onChange={setGallery} maxImages={10} />
+    </ImageUploadProvider>
+  );
+}
+```
+
+### 3. Build-Time Blur Manifests & Runtime Lookup (`/cli` & `/blur`)
+
+```bash
+npx img-upload-kit generate --dir ./public/images --out ./src/blur-manifest.json
+```
+```ts
+import { createBlurService } from 'img-upload-kit/blur';
+import manifest from './blur-manifest.json';
+
+const blurService = createBlurService({ manifest });
+const { color, blur: blurDataUrl } = blurService.getProgressiveData('/images/hero.avif');
+```
+
+---
+
+## The 4 Styling Tiers
+
+Customize UI components cleanly at any level of abstraction:
+
+### Tier 1: CSS Variables (`--iuk-*`) & Automatic Dark Mode
+```css
+:root {
+  --iuk-primary: #4f46e5;
+  --iuk-primary-hover: #4338ca;
+  --iuk-radius-md: 14px;
+}
+.dark { --iuk-primary: #818cf8; --iuk-surface: #0f172a; }
+```
+
+### Tier 2: Unstyled Mode with `classNames` & `data-[state=*]` (Tailwind CSS)
+```tsx
+<SingleImageUpload
+  unstyled value={avatar} onChange={setAvatar}
+  classNames={{
+    dropzone: 'rounded-2xl border-2 border-dashed p-6 text-center data-[state=dragging]:border-indigo-500',
+    browseButton: 'rounded-lg bg-indigo-600 px-4 py-2 text-white',
+  }}
+/>
+```
+
+### Tier 3: Partial Slot Renderers
+```tsx
+<SingleImageUpload
+  value={avatar} onChange={setAvatar}
+  renderDropzone={(ctx) => (
+    <div {...ctx.dropzoneProps} className="p-8 border border-dashed rounded-xl">
+      <button type="button" onClick={ctx.openFileDialog}>Select Photo</button>
+    </div>
+  )}
+/>
+```
+
+### Tier 4: Headless Hooks & Primitives (`/headless`)
+```tsx
+import { HeadlessSingleUpload, useDropzone } from 'img-upload-kit/headless';
+
+<HeadlessSingleUpload preset="avatar" value={avatar} onChange={setAvatar}>
+  {(ctrl) => (
+    <div {...ctrl.getDropzoneProps()}>
+      <input {...ctrl.getInputProps()} />
+      {ctrl.preview ? <img src={ctrl.preview} alt="" /> : <button type="button" onClick={ctrl.openFileDialog}>Upload</button>}
+    </div>
+  )}
+</HeadlessSingleUpload>
+```
+
+---
+
+## AnimatedImage (Blur-Up Display Component)
+
+`<AnimatedImage />` provides an instant blur-up placeholder crossfade to full resolution without layout shift:
+
+```tsx
+import { AnimatedImage } from 'img-upload-kit/react';
+import 'img-upload-kit/styles.css';
+
+// 1. Direct shorthand with UploadedImageData:
+<AnimatedImage image={img} showShimmer />
+
+// 2. Explicit props in standard React:
+<AnimatedImage
+  src={img.url}
+  alt={img.altText || 'Product'}
+  blurDataUrl={img.blurDataUrl}
+  blurHash={img.blurHash}
+  blurColor={img.blurColor}
+  width={800}
+  height={600}
+  showShimmer
+/>
+
+// 3. Next.js App Router (as={Image}):
+import Image from 'next/image';
+<div style={{ position: 'relative', aspectRatio: '16/9' }}>
+  <AnimatedImage image={img} as={Image} fill sizes="100vw" imageComponentProps={{ priority: true, quality: 80 }} />
+</div>
+```
+
+---
+
+## Documentation
+
+- [AI Agent Contributor Guide (`AGENTS.md`)](./AGENTS.md) — Architecture, guardrails, and styling tiers for AI agents.
+- [Custom Styling & Headless Guide (`docs/CUSTOM_STYLING.md`)](./docs/CUSTOM_STYLING.md) — Theming, slots, and headless recipes.
+- [AnimatedImage & Blur-Up Guide (`docs/ANIMATED_IMAGE.md`)](./docs/ANIMATED_IMAGE.md) — Progressive reveal component architecture.
+- [Architecture & Internals (`docs/ARCHITECTURE.md`)](./docs/ARCHITECTURE.md) — Sharp size-guarding and 4-edge color math.
+- [Framework & Storage Recipes (`docs/FRAMEWORK_RECIPES.md`)](./docs/FRAMEWORK_RECIPES.md) — Next.js, Hono, Remix, S3, Supabase recipes.
+- [Interactive Studio Code](https://github.com/MoElsherbiny/image-upload-kit-studio) — Source for the live demo playground.
+- [Contributing Guide (`CONTRIBUTING.md`)](./CONTRIBUTING.md) & [Changelog (`CHANGELOG.md`)](./CHANGELOG.md).
+
+## License & Author
+
+**Author & Identity**: [buildwithsherbo](https://www.buildwithsherbo.com/) — Mohamed Elsherbiny
+- **Website**: [buildwithsherbo.com](https://www.buildwithsherbo.com/)
+- **Live Demo**: [upload-kit.buildwithsherbo.com](https://upload-kit.buildwithsherbo.com)
+- **GitHub**: [@MoElsherbiny](https://github.com/MoElsherbiny)
+- **Email**: [mo@buildwithsherbo.com](mailto:mo@buildwithsherbo.com)
+
+Distributed under the [MIT License](./LICENSE).