smart-glide-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shadi Shammaa
+
+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

@@ -0,0 +1,333 @@
+# smart-glide-react
+
+> Official React & Next.js SDK for [Laravel Smart Glide](https://github.com/shammaa/laravel-smart-glide).
+> Responsive images · Blur placeholders · AVIF/WebP auto-negotiation · JSON-LD SEO · Next.js ISR support.
+
+[![npm version](https://img.shields.io/npm/v/smart-glide-react.svg)](https://www.npmjs.com/package/smart-glide-react)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
+
+---
+
+## Installation
+
+```bash
+npm install smart-glide-react
+# or
+pnpm add smart-glide-react
+# or
+yarn add smart-glide-react
+```
+
+---
+
+## Quick Start
+
+### 1. Set up environment variables
+
+```env
+# .env.local  (Next.js)
+NEXT_PUBLIC_SMART_GLIDE_URL=https://your-laravel-app.com
+NEXT_PUBLIC_SMART_GLIDE_DELIVERY_PATH=/img
+NEXT_PUBLIC_SMART_GLIDE_DATA_PATH=/img-data
+```
+
+### 2. Wrap your app with the Provider
+
+```tsx
+// app/layout.tsx  (Next.js App Router)
+import { SmartGlideProvider } from 'smart-glide-react';
+
+export default function RootLayout({ children }) {
+  return (
+    <SmartGlideProvider
+      config={{ baseUrl: process.env.NEXT_PUBLIC_SMART_GLIDE_URL }}
+    >
+      {children}
+    </SmartGlideProvider>
+  );
+}
+```
+
+### 3. Use the component
+
+```tsx
+import { SmartGlideImage } from 'smart-glide-react';
+
+export default function ProductCard() {
+  return (
+    <SmartGlideImage
+      path="products/phone.jpg"
+      alt="Awesome Phone"
+      profile="hero"
+      responsive="retina"
+      width={800}
+      height={600}
+    />
+  );
+}
+```
+
+---
+
+## `<SmartGlideImage>`
+
+The main image component — drop-in for `next/image` or a plain `<img>`.
+
+```tsx
+<SmartGlideImage
+  // Required
+  path="home/hero.jpg"
+  alt="Hero banner"
+
+  // Profile & responsive
+  profile="hero"            // named compression profile
+  responsive="fhd"          // named responsive set  |  [640, 960, 1280]  |  false
+
+  // LCP / priority
+  priority                  // fetchpriority="high" + loading="eager"
+
+  // Blur placeholder
+  placeholder="blur"        // show blurred LQIP while loading
+  blurPlaceholder           // fetch blur data from API
+
+  // SEO
+  schema                    // emit JSON-LD <ImageObject> after <img>
+
+  // Layout
+  width={1600}
+  height={900}
+  aspectRatio="16 / 9"
+
+  // Extra Glide params
+  params={{ fit: 'crop', focus: 'center' }}
+
+  // Config override (if not using Provider)
+  baseUrl="https://api.example.com"
+
+  // All native <img> attributes
+  className="rounded-xl shadow"
+  style={{ objectFit: 'cover' }}
+  onLoad={() => console.log('loaded!')}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | `string` | **required** | Relative image path inside Smart Glide source |
+| `alt` | `string` | **required** | Alt text (accessibility + SEO) |
+| `profile` | `ImageProfile` | `"default"` | Named compression profile |
+| `responsive` | `string \| number[] \| false` | `"retina"` | Breakpoints for `srcset` |
+| `priority` | `boolean` | `false` | LCP image — high fetch priority + eager loading |
+| `placeholder` | `"blur" \| "empty"` | `"empty"` | Blur LQIP while loading |
+| `blurPlaceholder` | `boolean` | `false` | Fetch blur data URI from API |
+| `schema` | `boolean` | `false` | Emit JSON-LD `ImageObject` |
+| `aspectRatio` | `string` | — | CSS `aspect-ratio` value |
+| `params` | `Record<string, string\|number>` | `{}` | Extra Glide params |
+| `baseUrl` | `string` | env var | Laravel app base URL |
+| `fetchOptions` | `RequestInit` | — | Options forwarded to `fetch()` |
+
+---
+
+## `<SmartGlidePicture>`
+
+Render `<picture>` with multiple `<source>` breakpoints.
+
+```tsx
+import { SmartGlidePicture } from 'smart-glide-react';
+
+<SmartGlidePicture
+  path="gallery/feature.jpg"
+  alt="Feature image"
+  sources={[
+    {
+      media: '(min-width: 1200px)',
+      widths: [1200],
+      params: { fit: 'crop', w: 1200, h: 675 },
+    },
+    {
+      media: '(min-width: 768px)',
+      widths: [900],
+      params: { w: 900, h: 506 },
+    },
+  ]}
+  profile="default"
+  width={900}
+  height={506}
+/>
+```
+
+---
+
+## `<SmartGlideBackground>`
+
+CSS background-image with responsive media queries.
+
+```tsx
+import { SmartGlideBackground } from 'smart-glide-react';
+
+<SmartGlideBackground
+  path="banners/summit.jpg"
+  profile="hero"
+  responsive="hero"
+  aria-label="Annual summit banner"
+  className="h-screen"
+>
+  <h1>Welcome</h1>
+</SmartGlideBackground>
+```
+
+---
+
+## Hooks
+
+### `useSmartGlide` — fetch from API
+
+```tsx
+import { useSmartGlide } from 'smart-glide-react';
+
+function MyImage() {
+  const { src, srcset, sizes, blurDataUrl, isLoading, error } = useSmartGlide({
+    path: 'products/phone.jpg',
+    profile: 'hero',
+    responsive: 'retina',
+    blurPlaceholder: true,
+    schema: true,
+  });
+
+  if (isLoading) return <Skeleton />;
+  if (error)     return <ErrorState />;
+
+  return (
+    <img src={src} srcSet={srcset ?? undefined} sizes={sizes ?? undefined} alt="Phone" />
+  );
+}
+```
+
+### `useSmartGlideStatic` — no API call
+
+Builds URLs entirely client-side. **URLs are unsigned** — use only when `SMART_GLIDE_SECURE=false`.
+
+```tsx
+import { useSmartGlideStatic } from 'smart-glide-react';
+
+const { src, srcset, sizes } = useSmartGlideStatic({
+  path: 'products/phone.jpg',
+  profile: 'thumbnail',
+  responsive: [320, 640, 960],
+});
+```
+
+---
+
+## Server-Side Data Fetching (Next.js App Router)
+
+```tsx
+// app/products/[id]/page.tsx  — Server Component
+import { fetchSmartGlideData } from 'smart-glide-react/server';
+
+export default async function ProductPage({ params }) {
+  const image = await fetchSmartGlideData({
+    path: `products/${params.id}.jpg`,
+    profile: 'hero',
+    responsive: 'retina',
+    blurPlaceholder: true,
+    schema: true,
+    baseUrl: process.env.SMART_GLIDE_URL,   // server-side env (no NEXT_PUBLIC_)
+    fetchOptions: { next: { revalidate: 3600 } }, // ISR
+  });
+
+  return (
+    <>
+      <img
+        src={image.src}
+        srcSet={image.srcset ?? undefined}
+        sizes={image.sizes ?? undefined}
+        alt={params.id}
+      />
+      {image.schema && (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(image.schema) }}
+        />
+      )}
+    </>
+  );
+}
+```
+
+### Fetch multiple images in parallel
+
+```tsx
+import { fetchSmartGlideMany } from 'smart-glide-react/server';
+
+const [hero, thumb, avatar] = await fetchSmartGlideMany([
+  { path: 'home/hero.jpg',    profile: 'hero',         responsive: 'fhd' },
+  { path: 'home/thumb.jpg',   profile: 'thumbnail',    responsive: 'thumbnails' },
+  { path: 'avatars/user.jpg', profile: 'profile_photo' },
+], { baseUrl: process.env.SMART_GLIDE_URL });
+```
+
+---
+
+## Next.js `Image` Loader
+
+Route `next/image` through Smart Glide for auto WebP/AVIF.
+
+**`next.config.ts`:**
+```ts
+const nextConfig = {
+  images: {
+    loader: 'custom',
+    loaderFile: './smart-glide-loader.ts',
+  },
+};
+export default nextConfig;
+```
+
+**`smart-glide-loader.ts`** (project root):
+```ts
+export { smartGlideNextLoader as default } from 'smart-glide-react/next';
+```
+
+Then use `next/image` normally — Smart Glide handles all resizing:
+```tsx
+import Image from 'next/image';
+
+<Image src="products/phone.jpg" width={800} height={600} alt="Phone" />
+```
+
+---
+
+## Available Profiles
+
+| Profile | Dimensions | Use case |
+|---------|-----------|----------|
+| `default` | WebP q82 | Generic |
+| `thumbnail` | 320×320 | Avatars, cards |
+| `hero` | 1600×900 | Hero banners |
+| `portrait` | 800×1200 | Faces, profiles |
+| `square` | 600×600 | Grids |
+| `profile_photo` | 400×400 | User avatars |
+| `cover` | 2048×1152 | Cover art |
+| `background` | 2560×1440 | Full backgrounds |
+
+## Available Responsive Sets
+
+| Name | Widths |
+|------|--------|
+| `hero` | 640, 960, 1280, 1600, 1920 |
+| `thumbnails` | 240, 320, 480 |
+| `square` | 320, 480, 640 |
+| `portrait` | 480, 768, 1024 |
+| `hd` | 960, 1280, 1600 |
+| `fhd` | 1280, 1600, 1920, 2560 |
+| `retina` | 640, 960, 1280, 1920, 2560 |
+
+---
+
+## License
+
+MIT © [Shadi Shammaa](https://github.com/shammaa)

package/dist/index.d.mts

@@ -0,0 +1,241 @@
+import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Named responsive presets available on the Laravel backend. */
+type ResponsivePreset = 'hero' | 'thumbnails' | 'square' | 'portrait' | 'hd' | 'fhd' | 'retina' | (string & {});
+/** Named image profiles available on the Laravel backend. */
+type ImageProfile = 'default' | 'thumbnail' | 'hero' | 'portrait' | 'square' | 'profile_photo' | 'cover' | 'background' | (string & {});
+/** Response shape returned by the `/img-data` API. */
+interface SmartGlideData {
+    src: string;
+    srcset?: string | null;
+    sizes?: string | null;
+    widths?: number[];
+    blurDataUrl?: string | null;
+    schema?: Record<string, unknown> | null;
+}
+/** Options passed to `useSmartGlide` and lower-level helpers. */
+interface SmartGlideOptions {
+    /** Relative path of the image (e.g. `"products/phone.jpg"`). */
+    path: string;
+    /**
+     * Base URL of your Laravel app (e.g. `"https://api.example.com"`).
+     * Defaults to the `NEXT_PUBLIC_SMART_GLIDE_URL` / `VITE_SMART_GLIDE_URL`
+     * environment variable when omitted.
+     */
+    baseUrl?: string;
+    /** Named or custom compression profile (default: `"default"`). */
+    profile?: ImageProfile;
+    /**
+     * Responsive breakpoints:
+     *  - `"hero"` — named preset
+     *  - `[640, 960, 1280]` — custom widths
+     *  - `false` — disable srcset
+     */
+    responsive?: ResponsivePreset | number[] | false;
+    /** Fetch the blurred Base64 LQIP from the server. Enables `blurDataUrl`. */
+    blurPlaceholder?: boolean;
+    /** Request JSON-LD `ImageObject` data from the server. */
+    schema?: boolean;
+    /** Extra Glide transformation params (w, h, fit, focus, q…). */
+    params?: Record<string, string | number>;
+    /**
+     * Additional fetch options forwarded to the underlying `fetch()` call.
+     * (e.g. `{ next: { revalidate: 3600 } }` for Next.js ISR)
+     */
+    fetchOptions?: RequestInit;
+}
+/** Props accepted by the `<SmartGlideImage>` component. */
+interface SmartGlideImageProps extends SmartGlideOptions {
+    /** Alt text — required for accessibility and SEO. */
+    alt: string;
+    /**
+     * Mark this image as a Largest Contentful Paint candidate.
+     * Sets `fetchpriority="high"` + `loading="eager"`.
+     */
+    priority?: boolean;
+    /**
+     * Show a blurred low-quality placeholder while the full image loads.
+     */
+    placeholder?: 'blur' | 'empty';
+    /** Inline aspect-ratio hint (e.g. `"16 / 9"`, `"1"`, `"4 / 3"`). */
+    aspectRatio?: string;
+    /** Width attribute for layout stability. */
+    width?: number;
+    /** Height attribute for layout stability. */
+    height?: number;
+    /** CSS class name. */
+    className?: string;
+    /** Inline styles. */
+    style?: React.CSSProperties;
+    /** Callback fired when the image fully loads. */
+    onLoad?: React.ReactEventHandler<HTMLImageElement>;
+    /** Callback fired on image error. */
+    onError?: React.ReactEventHandler<HTMLImageElement>;
+}
+
+/**
+ * A full-featured, SEO-optimised `<img>` component backed by Laravel Smart Glide.
+ *
+ * @example
+ * <SmartGlideImage
+ *   path="products/phone.jpg"
+ *   alt="Awesome Phone"
+ *   profile="hero"
+ *   responsive="retina"
+ * />
+ *
+ * @example
+ * <SmartGlideImage
+ *   path="home/hero.jpg"
+ *   alt="Hero banner"
+ *   profile="hero"
+ *   priority
+ *   placeholder="blur"
+ *   blurPlaceholder
+ *   schema
+ *   width={1600}
+ *   height={900}
+ * />
+ */
+declare const SmartGlideImage: React.ForwardRefExoticComponent<SmartGlideImageProps & React.RefAttributes<HTMLImageElement>>;
+interface SmartGlidePictureSource {
+    media?: string;
+    widths?: number[];
+    responsive?: string | number[];
+    params?: Record<string, string | number>;
+    type?: string;
+}
+interface SmartGlidePictureProps extends SmartGlideImageProps {
+    sources?: SmartGlidePictureSource[];
+}
+/**
+ * `<picture>` component with multiple `<source>` breakpoints
+ * plus a Smart Glide powered `<img>` fallback.
+ */
+declare const SmartGlidePicture: React.ForwardRefExoticComponent<SmartGlidePictureProps & React.RefAttributes<HTMLImageElement>>;
+interface SmartGlideBackgroundProps extends SmartGlideOptions {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    'aria-label'?: string;
+}
+/**
+ * CSS background-image container backed by Smart Glide.
+ */
+declare const SmartGlideBackground: React.FC<SmartGlideBackgroundProps>;
+
+interface SmartGlideConfig {
+    /** Base URL of your Laravel application (e.g. `"https://api.example.com"`). */
+    baseUrl?: string;
+    /** Delivery path prefix (default: `"/img"`). */
+    deliveryPath?: string;
+    /** Data API path prefix (default: `"/img-data"`). */
+    dataPath?: string;
+    /** Default image profile to apply when none is specified. */
+    defaultProfile?: string;
+    /** Default responsive set name or widths. */
+    defaultResponsive?: string | number[];
+    /** Emit JSON-LD `ImageObject` by default for all images. */
+    defaultSchema?: boolean;
+}
+declare function useSmartGlideConfig(): SmartGlideConfig;
+interface SmartGlideProviderProps {
+    config: SmartGlideConfig;
+    children: React.ReactNode;
+}
+/**
+ * Wrap your application (or part of it) with `<SmartGlideProvider>` to
+ * configure Smart Glide globally. Individual components/hooks can still
+ * override any option locally.
+ *
+ * @example
+ * // app/layout.tsx  (Next.js App Router)
+ * import { SmartGlideProvider } from 'smart-glide-react';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <SmartGlideProvider config={{ baseUrl: process.env.NEXT_PUBLIC_API_URL }}>
+ *       {children}
+ *     </SmartGlideProvider>
+ *   );
+ * }
+ */
+declare function SmartGlideProvider({ config, children }: SmartGlideProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseSmartGlideResult {
+    /** Final signed delivery URL (ready for `<img src>`). */
+    src: string;
+    /** Responsive srcset string. */
+    srcset: string | null;
+    /** Sizes attribute. */
+    sizes: string | null;
+    /** Base64 LQIP blur data URI for placeholder. */
+    blurDataUrl: string | null;
+    /** JSON-LD ImageObject schema data. */
+    schema: Record<string, unknown> | null;
+    /** True while fetching from the API. */
+    isLoading: boolean;
+    /** Error if the fetch failed. */
+    error: Error | null;
+    /** Manually re-fetch the data. */
+    refetch: () => void;
+}
+/**
+ * Fetch Smart Glide image data from the Laravel API.
+ *
+ * @example
+ * const { src, srcset, sizes, blurDataUrl } = useSmartGlide({
+ *   path: 'products/phone.jpg',
+ *   profile: 'hero',
+ *   responsive: 'retina',
+ *   blurPlaceholder: true,
+ *   baseUrl: process.env.NEXT_PUBLIC_API_URL,
+ * });
+ */
+declare function useSmartGlide(options: SmartGlideOptions): UseSmartGlideResult;
+interface UseSmartGlideStaticResult {
+    src: string;
+    srcset: string;
+    sizes: string;
+}
+/**
+ * Build image URLs entirely client-side — no API fetch required.
+ * Ideal for Next.js App Router with `generateStaticParams` or ISR.
+ *
+ * NOTE: URLs generated here are **unsigned**. Use this only in development
+ * or when `SMART_GLIDE_SECURE=false` on your Laravel backend.
+ * For signed URLs, use `useSmartGlide` or server-side data fetching.
+ */
+declare function useSmartGlideStatic(options: SmartGlideOptions): UseSmartGlideStaticResult;
+
+/** Resolve the base URL from options or environment variables. */
+declare function resolveBaseUrl(baseUrl?: string): string;
+/** Resolve the delivery path prefix (default: `/img`). */
+declare function resolveDeliveryPath(deliveryPath?: string): string;
+/** Resolve the data API path prefix (default: `/img-data`). */
+declare function resolveDataPath(dataPath?: string): string;
+/** Build a single Smart Glide delivery URL (unsigned — for preview/dev). */
+declare function buildDeliveryUrl(path: string, params?: Record<string, string | number>, options?: {
+    baseUrl?: string;
+    deliveryPath?: string;
+}): string;
+/** Build the JSON data API URL for a given path. */
+declare function buildDataUrl(path: string, options: SmartGlideOptions & {
+    deliveryPath?: string;
+    dataPath?: string;
+}): string;
+declare function resolveWidths(responsive?: string | number[] | false | null): number[];
+/**
+ * Build srcset and sizes strings entirely client-side
+ * (no API call — for use with Next.js custom loader or static generation).
+ */
+declare function buildSrcSet(path: string, params?: Record<string, string | number>, widths?: number[], options?: {
+    baseUrl?: string;
+    deliveryPath?: string;
+}): {
+    srcset: string;
+    sizes: string;
+};
+
+export { type ImageProfile, type ResponsivePreset, SmartGlideBackground, type SmartGlideBackgroundProps, type SmartGlideConfig, type SmartGlideData, SmartGlideImage, type SmartGlideImageProps, type SmartGlideOptions, SmartGlidePicture, type SmartGlidePictureProps, type SmartGlidePictureSource, SmartGlideProvider, type SmartGlideProviderProps, type UseSmartGlideResult, type UseSmartGlideStaticResult, buildDataUrl, buildDeliveryUrl, buildSrcSet, resolveBaseUrl, resolveDataPath, resolveDeliveryPath, resolveWidths, useSmartGlide, useSmartGlideConfig, useSmartGlideStatic };