react-a11y-auto-caption 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +94 -78
  2. package/package.json +26 -11
package/README.md CHANGED
@@ -1,53 +1,66 @@
1
1
  # react-a11y-auto-caption
2
2
 
3
3
  > A smart React & Next.js component <br/>
4
- that automatically generates highly accurate `alt` text for images using AI.<br/>
5
- **Generate captions effortlessly during local development, <br/>
6
- save them to your database, and serve 100% accessible images in production<br/>
7
- with zero API costs and zero latency.**
4
+ > that automatically generates highly accurate `alt` text for images using AI.<br/>
5
+ > **Generate captions effortlessly during local development, <br/>
6
+ > save them to your database, and serve 100% accessible images in production<br/>
7
+ > with zero API costs and zero latency.**
8
8
 
9
9
  [![npm version](https://img.shields.io/npm/v/react-a11y-auto-caption.svg)](https://www.npmjs.com/package/react-a11y-auto-caption)
10
10
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11
11
  [![Accessibility](https://img.shields.io/badge/Accessibility-100%25-brightgreen.svg)]()
12
12
 
13
+ ---
14
+
13
15
  ## Why use this library?
14
16
 
15
- - **Generate Once, Serve Forever (Best Practice):** Automatically generate captions during local development, easily save them to your database using the `onCaptionGenerated` callback, and completely bypass AI requests in production.
17
+ - **Generate Once, Serve Forever (Best Practice):** Automatically generate captions during local development, easily save them to your database using the `onCaptionGenerated` callback, and completely bypass AI requests in production.
16
18
  - **Cost-Free Local AI Server:** Comes with a ready-to-use, lightweight FastAPI Python server. It runs perfectly on your local machine, meaning you don't need to pay for expensive cloud GPUs or third-party API subscriptions (like OpenAI).
17
19
  - **Zero-Config Accessibility:** Automatically describes images for screen readers without manual data entry.
18
- - **First-Class Next.js Support:** Provides a dedicated `<SmartNextImage>` component optimized for Next.js.
19
- - **Smart Request Caching:** Built-in memory caching prevents duplicate API calls for the same image, saving your server costs.
20
+ - **First-Class Next.js Support:** Provides a dedicated `<SmartNextImage>` component optimized for Next.js, supporting both static imports and URL strings.
21
+ - **Smart LRU Caching:** Built-in LRU memory cache (max 500 entries) prevents duplicate API calls and unbounded memory growth.
20
22
  - **Concurrent Request Defense:** Safely handles simultaneous renders of the same image across multiple components.
23
+ - **Reliable Error Handling:** Exposes errors via both `onCaptionError` callback and returned `error` state for full control over failure UX.
21
24
  - **Global Provider Pattern:** Set your API endpoint once at the root level and forget about it.
22
25
  - **Developer Experience (DX):** Built-in test mode (`disableAI`) and intelligent console warnings for smooth debugging.
23
26
 
24
27
  ---
25
28
 
29
+ ## What's New in v1.1.0
30
+
31
+ - **LRU Cache:** Replaced unbounded `Map` cache with an LRU implementation to prevent memory leaks in long-running apps.
32
+ - **`onCaptionError` callback:** New prop to handle caption generation failures externally (e.g. logging, toast notifications).
33
+ - **`error` state:** `useAICaptions` hook now returns an `error` field so you can branch your UI on failure.
34
+ - **Unmount safety:** Caption generation is now safely cancelled when a component unmounts, preventing stale state updates.
35
+ - **Next.js static import support:** `<SmartNextImage>` now correctly resolves both `StaticImageData` and `StaticRequire` import types.
36
+ - **Subpath exports:** Added `react-a11y-auto-caption/next` entry point for cleaner Next.js-specific imports.
37
+
38
+ ---
39
+
26
40
  ## Installation
27
41
 
28
- npm
29
42
  ```bash
43
+ # npm
30
44
  npm install react-a11y-auto-caption
31
- ```
32
- yarn berry
33
- ```bash
45
+
46
+ # yarn
34
47
  yarn add react-a11y-auto-caption
35
- ```
36
- pnpm
37
- ```bash
48
+
49
+ # pnpm
38
50
  pnpm add react-a11y-auto-caption
39
51
  ```
40
52
 
41
53
  ---
54
+
42
55
  ## Quick Start
43
56
 
44
- ### 1. Wrap your app with the Provider (Optional but Recommended) <br/>
45
- Set your backend API endpoint once globally. <br/>
46
- Otherwise, you can simply pass apiEndpoint as a prop when using `<SmartImage>` <br/>
57
+ ### 1. Wrap your app with the Provider (Optional but Recommended)
47
58
 
48
- ```ts
59
+ Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
60
+
61
+ ```tsx
49
62
  // App.tsx or layout.tsx
50
- import { SmartImageProvider } from 'react-a11y-auto-caption';
63
+ import { SmartImageProvider } from "react-a11y-auto-caption";
51
64
 
52
65
  export default function App({ children }) {
53
66
  return (
@@ -57,96 +70,99 @@ export default function App({ children }) {
57
70
  );
58
71
  }
59
72
  ```
73
+
60
74
  ### 2. Use it in your components
61
- For Vanilla React (Vite, CRA):<br/>
62
- ```ts
63
- import { SmartImage } from 'react-a11y-auto-caption';
75
+
76
+ **Vanilla React (Vite, CRA):**
77
+
78
+ ```tsx
79
+ import { SmartImage } from "react-a11y-auto-caption";
64
80
 
65
81
  function Gallery() {
66
- return (
67
- <SmartImage
68
- src="[https://example.com/beautiful-landscape.jpg](https://example.com/beautiful-landscape.jpg)"
69
- announceLive={true}
70
- />
71
- );
82
+ return <SmartImage src="https://example.com/beautiful-landscape.jpg" announceLive={true} />;
72
83
  }
73
84
  ```
74
85
 
75
- For Next.js: <br/>
76
- ```ts
77
- import { SmartNextImage } from 'react-a11y-auto-caption';
78
- import dogPic from '../public/dog.jpg';
86
+ **Next.js:**
87
+
88
+ ```tsx
89
+ import { SmartNextImage } from "react-a11y-auto-caption/next";
90
+ import dogPic from "../public/dog.jpg";
79
91
 
80
92
  function NextGallery() {
81
- return (
82
- <SmartNextImage
83
- src={dogPic}
84
- width={500}
85
- height={300}
86
- // You can override global settings per component
87
- disableAI={process.env.NODE_ENV === 'development'}
88
- />
89
- );
93
+ return <SmartNextImage src={dogPic} width={500} height={300} disableAI={process.env.NODE_ENV === "production"} />;
90
94
  }
91
95
  ```
92
- ---
93
96
 
94
- ## API Reference
95
- Both `SmartImage` and `SmartNextImage` inherit all standard `<img>` / `next/image` props, plus the following: <br/>
96
- ## API Reference (Props)
97
+ ---
97
98
 
98
- Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes. The following custom props are available:
99
+ ## API Reference
99
100
 
100
- | Prop | Type | Default | Description |
101
- | :--- | :--- | :--- | :--- |
102
- | `apiEndpoint` | `string` | `undefined` | The URL of your AI backend API. Overrides the `SmartImageProvider`'s endpoint if provided. |
103
- | `alt` | `string` | `undefined` | Manual alt text. If provided, the AI generation is completely bypassed. |
104
- | `fallbackAlt` | `string` | `"Image loading or caption unavailable"` | The text displayed if the AI API request fails or times out. |
105
- | `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Highly recommended for local development and testing. |
106
- | `announceLive` | `boolean` | `false` | Enables `aria-live` regions to dynamically announce the generation status to screen readers. |
107
- | `onCaptionGenerated`| `function` | `undefined` | Callback fired when a caption is successfully generated. `(caption: string) => void` |
101
+ Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
108
102
 
109
- > **Note:** If you are using `<SmartNextImage>`, you must also provide standard required Next.js image props such as `width` and `height` (unless using `fill`).
110
- ---
111
- ## Security & Backend Integration
103
+ | Prop | Type | Default | Description |
104
+ | :------------------- | :-------------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------- |
105
+ | `apiEndpoint` | `string` | `undefined` | The URL of your AI backend API. Overrides the `SmartImageProvider` endpoint if provided. |
106
+ | `alt` | `string` | `undefined` | Manual alt text. If provided, AI generation is completely bypassed. |
107
+ | `fallbackAlt` | `string` | `"Image loading or caption unavailable"` | Text used when the AI request fails or times out. |
108
+ | `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Recommended for testing. |
109
+ | `announceLive` | `boolean` | `false` | Enables `aria-live` region to announce generation status to screen readers. |
110
+ | `onCaptionGenerated` | `(caption: string) => void` | `undefined` | Callback fired when a caption is successfully generated. |
111
+ | `onCaptionError` | `(error: Error) => void` | `undefined` | Callback fired when caption generation fails. Use for logging or toast notifications. |
112
112
 
113
- This package requires a backend to process the images through an AI model (like ViT-GPT2). <br/>
114
- We provide a ready-to-use FastAPI reference server in [this repository.](https://github.com/kong33/SmartImage)<br/>
113
+ > **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
115
114
 
116
- Depending on your architecture, choose one of the following integration methods:<br/>
117
115
  ---
118
- ### First step: Deploying our Standalone AI Microservice
119
- For security reasons, all cross-origin requests are blocked by default. <br/>
120
- You MUST set the ALLOWED_ORIGINS environment variable in your server's .env file<br/>
121
- to allow your frontend to communicate with it. <br/>
122
116
 
117
+ ## Error Handling
118
+
119
+ You can handle errors in two ways depending on your use case.
123
120
 
124
- ```python
125
- # For production
121
+ **Via callback** — for external handling like logging or toasts:
126
122
 
127
- # .env file on your Python server
128
- ALLOWED_ORIGINS=https://your-frontend-domain.com,https://your-frontend-domain2.com
123
+ ```tsx
124
+ <SmartImage src={imageUrl} onCaptionError={(err) => toast.error(err.message)} />
129
125
  ```
130
- ```python
131
- # For local development
132
126
 
133
- # .env file on your Python server
134
- ALLOWED_ORIGINS=http://localhost:3000
127
+ **Via `useAICaptions` hook** — for UI branching:
128
+
129
+ ```tsx
130
+ const { generatedAlt, isGenerating, error } = useAICaptions({ src });
131
+
132
+ if (error) return <p>Failed to generate caption.</p>;
135
133
  ```
136
- > **Note:** Change the port if you are using Vite 5173 or another local server. You can allow multiple environments simultaneously by separating them with a comma (no spaces).
137
134
 
138
135
  ---
139
136
 
140
137
  ## Best Practice: Generate Once, Save, Reuse
141
- Generating captions on-the-fly for every user is slow. <br/>
142
- The industry standard is to generate the caption once and save it to your database:
138
+
139
+ Generating captions on-the-fly for every user is slow. The recommended pattern is to generate once and persist to your database:
143
140
 
144
141
  ```tsx
145
- <SmartImage
142
+ <SmartImage
146
143
  src={image.url}
147
- alt={image.savedAlt} // If provided, the AI sleeps!
144
+ alt={image.savedAlt} // If provided, AI is skipped entirely
148
145
  apiEndpoint="http://localhost:8000/api/generate-caption"
149
146
  onCaptionGenerated={(text) => {
150
- saveToDatabase(image.id, text); // Save permanently (You create your own database saving function based on your code.)
147
+ saveToDatabase(image.id, text);
151
148
  }}
152
149
  />
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Security & Backend Integration
155
+
156
+ This package requires a backend to process images through an AI model (e.g. ViT-GPT2). We provide a ready-to-use FastAPI reference server in [this repository](https://github.com/kong33/SmartImage).
157
+
158
+ For security, all cross-origin requests are blocked by default. Set the `ALLOWED_ORIGINS` environment variable in your server's `.env` file:
159
+
160
+ ```bash
161
+ # Production
162
+ ALLOWED_ORIGINS=https://your-frontend-domain.com
163
+
164
+ # Local development
165
+ ALLOWED_ORIGINS=http://localhost:3000
166
+ ```
167
+
168
+ > **Note:** Separate multiple origins with a comma and no spaces. Adjust the port if using Vite (`5173`) or another local server.
package/package.json CHANGED
@@ -1,10 +1,28 @@
1
1
  {
2
2
  "name": "react-a11y-auto-caption",
3
- "version": "1.0.3",
3
+ "version": "1.0.4",
4
4
  "description": "Smart React component that automatically generates alt text for images using AI.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
7
7
  "types": "./dist/index.d.ts",
8
+ "keywords": [
9
+ "react",
10
+ "accessibility",
11
+ "a11y",
12
+ "alt-text",
13
+ "image-caption",
14
+ "caption-generator",
15
+ "screen-reader",
16
+ "nextjs"
17
+ ],
18
+ "homepage": "https://github.com/kong33/react-a11y-auto-caption#readme",
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "https://github.com/kong33/react-a11y-auto-caption"
22
+ },
23
+ "bugs": {
24
+ "url": "https://github.com/kong33/react-a11y-auto-caption/issues"
25
+ },
8
26
  "exports": {
9
27
  ".": {
10
28
  "import": "./dist/index.js",
@@ -19,14 +37,6 @@
19
37
  "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationDir ./dist",
20
38
  "dev": "tsup --watch"
21
39
  },
22
- "keywords": [
23
- "react",
24
- "accessibility",
25
- "a11y",
26
- "ai",
27
- "image-captioning",
28
- "alt-text"
29
- ],
30
40
  "author": "Gaeun Kim",
31
41
  "license": "MIT",
32
42
  "devDependencies": {
@@ -50,6 +60,11 @@
50
60
  }
51
61
  },
52
62
  "files": [
53
- "dist"
54
- ]
63
+ "dist",
64
+ "README.md",
65
+ "LICENSE"
66
+ ],
67
+ "publishConfig": {
68
+ "access": "public"
69
+ }
55
70
  }