react-a11y-auto-caption 1.0.5 → 1.0.8
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.
- package/README.md +82 -81
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,60 +1,60 @@
|
|
|
1
1
|
# react-a11y-auto-caption
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
>
|
|
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.**
|
|
3
|
+
> AI-powered alt text generation for React and Next.js images.
|
|
4
|
+
> Generate captions during development, save them once, and reuse them in production for fast, accessible images.
|
|
8
5
|
|
|
9
6
|
[](https://www.npmjs.com/package/react-a11y-auto-caption)
|
|
10
7
|
[](https://opensource.org/licenses/MIT)
|
|
11
8
|
[]()
|
|
12
9
|
|
|
13
10
|
---
|
|
11
|
+
## Why use react-a11y-auto-caption?
|
|
14
12
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
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.
|
|
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.
|
|
24
|
-
- **Global Provider Pattern:** Set your API endpoint once at the root level and forget about it.
|
|
25
|
-
- **Developer Experience (DX):** Built-in test mode (`disableAI`) and intelligent console warnings for smooth debugging.
|
|
13
|
+
- **Generate once, reuse forever** — create captions during development, save them, and skip AI calls in production.
|
|
14
|
+
- **Built for accessibility** — automatically provide meaningful alt text for screen readers.
|
|
15
|
+
- **Works with React and Next.js** — includes both `<SmartImage>` and `<SmartNextImage>`.
|
|
16
|
+
- **Bring your own backend** — use your own FastAPI, Flask, or Node caption API.
|
|
17
|
+
- **Production-friendly** — caching, duplicate-request protection, and error handling are built in.
|
|
26
18
|
|
|
27
19
|
---
|
|
28
20
|
|
|
29
|
-
##
|
|
21
|
+
## Quick Start
|
|
30
22
|
|
|
31
|
-
|
|
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.
|
|
23
|
+
### React
|
|
37
24
|
|
|
38
|
-
|
|
25
|
+
```tsx
|
|
26
|
+
import { SmartImage } from 'react-a11y-auto-caption';
|
|
39
27
|
|
|
40
|
-
|
|
28
|
+
export default function Demo() {
|
|
29
|
+
return (
|
|
30
|
+
<SmartImage
|
|
31
|
+
src="https://example.com/image.jpg"
|
|
32
|
+
apiEndpoint="http://localhost:8000/api/generate-caption"
|
|
33
|
+
/>
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
```
|
|
41
37
|
|
|
42
|
-
|
|
43
|
-
# npm
|
|
44
|
-
npm install react-a11y-auto-caption
|
|
38
|
+
### Next.js
|
|
45
39
|
|
|
46
|
-
|
|
47
|
-
|
|
40
|
+
```tsx
|
|
41
|
+
import { SmartNextImage } from 'react-a11y-auto-caption/next';
|
|
42
|
+
import sampleImage from '../public/sample.jpg';
|
|
48
43
|
|
|
49
|
-
|
|
50
|
-
|
|
44
|
+
export default function Demo() {
|
|
45
|
+
return (
|
|
46
|
+
<SmartNextImage
|
|
47
|
+
src={sampleImage}
|
|
48
|
+
width={500}
|
|
49
|
+
height={300}
|
|
50
|
+
apiEndpoint="http://localhost:8000/api/generate-caption"
|
|
51
|
+
/>
|
|
52
|
+
);
|
|
53
|
+
}
|
|
51
54
|
```
|
|
55
|
+
> **Optional**: set the API endpoint once with a Provider
|
|
52
56
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
## Quick Start
|
|
56
|
-
|
|
57
|
-
### 1. Wrap your app with the Provider (Optional but Recommended)
|
|
57
|
+
### Wrap your app with the Provider (Optional but Recommended)
|
|
58
58
|
|
|
59
59
|
Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
|
|
60
60
|
|
|
@@ -71,28 +71,28 @@ export default function App({ children }) {
|
|
|
71
71
|
}
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
---
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
## Installation
|
|
77
77
|
|
|
78
|
-
```
|
|
79
|
-
|
|
78
|
+
```bash
|
|
79
|
+
# npm
|
|
80
|
+
npm install react-a11y-auto-caption
|
|
80
81
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
}
|
|
84
|
-
```
|
|
82
|
+
# yarn
|
|
83
|
+
yarn add react-a11y-auto-caption
|
|
85
84
|
|
|
86
|
-
|
|
85
|
+
# pnpm
|
|
86
|
+
pnpm add react-a11y-auto-caption
|
|
87
|
+
```
|
|
87
88
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
import dogPic from "../public/dog.jpg";
|
|
89
|
+
---
|
|
90
|
+
## Recommended workflow
|
|
91
91
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
92
|
+
1. Generate captions during local development with light [python server](https://github.com/kong33/SmartImage)
|
|
93
|
+
2. Save them to your database with `onCaptionGenerated`
|
|
94
|
+
3. Pass the saved `alt` text in production
|
|
95
|
+
4. Skip AI requests entirely for zero extra latency
|
|
96
96
|
|
|
97
97
|
---
|
|
98
98
|
|
|
@@ -100,15 +100,15 @@ function NextGallery() {
|
|
|
100
100
|
|
|
101
101
|
Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
|
|
102
102
|
|
|
103
|
-
| Prop
|
|
104
|
-
|
|
|
105
|
-
| `apiEndpoint`
|
|
106
|
-
| `alt`
|
|
107
|
-
| `fallbackAlt`
|
|
108
|
-
| `disableAI`
|
|
109
|
-
| `announceLive`
|
|
110
|
-
| `onCaptionGenerated` | `(caption: string) => void` | `undefined`
|
|
111
|
-
| `onCaptionError`
|
|
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
113
|
> **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
|
|
114
114
|
|
|
@@ -121,7 +121,10 @@ You can handle errors in two ways depending on your use case.
|
|
|
121
121
|
**Via callback** — for external handling like logging or toasts:
|
|
122
122
|
|
|
123
123
|
```tsx
|
|
124
|
-
<SmartImage
|
|
124
|
+
<SmartImage
|
|
125
|
+
src={imageUrl}
|
|
126
|
+
onCaptionError={(err) => toast.error(err.message)}
|
|
127
|
+
/>
|
|
125
128
|
```
|
|
126
129
|
|
|
127
130
|
**Via `useAICaptions` hook** — for UI branching:
|
|
@@ -134,26 +137,10 @@ if (error) return <p>Failed to generate caption.</p>;
|
|
|
134
137
|
|
|
135
138
|
---
|
|
136
139
|
|
|
137
|
-
## Best Practice: Generate Once, Save, Reuse
|
|
138
|
-
|
|
139
|
-
Generating captions on-the-fly for every user is slow. The recommended pattern is to generate once and persist to your database:
|
|
140
|
-
|
|
141
|
-
```tsx
|
|
142
|
-
<SmartImage
|
|
143
|
-
src={image.url}
|
|
144
|
-
alt={image.savedAlt} // If provided, AI is skipped entirely
|
|
145
|
-
apiEndpoint="http://localhost:8000/api/generate-caption"
|
|
146
|
-
onCaptionGenerated={(text) => {
|
|
147
|
-
saveToDatabase(image.id, text);
|
|
148
|
-
}}
|
|
149
|
-
/>
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
---
|
|
153
|
-
|
|
154
140
|
## Security & Backend Integration
|
|
155
141
|
|
|
156
|
-
This package requires a backend to process images through an AI model (e.g. ViT-GPT2).
|
|
142
|
+
This package requires a backend to process images through an AI model (e.g. ViT-GPT2). <br/>
|
|
143
|
+
We provide a ready-to-use FastAPI reference server in [this repository](https://github.com/kong33/SmartImage).
|
|
157
144
|
|
|
158
145
|
For security, all cross-origin requests are blocked by default. Set the `ALLOWED_ORIGINS` environment variable in your server's `.env` file:
|
|
159
146
|
|
|
@@ -166,3 +153,17 @@ ALLOWED_ORIGINS=http://localhost:3000
|
|
|
166
153
|
```
|
|
167
154
|
|
|
168
155
|
> **Note:** Separate multiple origins with a comma and no spaces. Adjust the port if using Vite (`5173`) or another local server.
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## What's New in v1.0.4
|
|
161
|
+
|
|
162
|
+
- **LRU Cache:** Replaced unbounded `Map` cache with an LRU implementation to prevent memory leaks in long-running apps.
|
|
163
|
+
- **`onCaptionError` callback:** New prop to handle caption generation failures externally (e.g. logging, toast notifications).
|
|
164
|
+
- **`error` state:** `useAICaptions` hook now returns an `error` field so you can branch your UI on failure.
|
|
165
|
+
- **Unmount safety:** Caption generation is now safely cancelled when a component unmounts, preventing stale state updates.
|
|
166
|
+
- **Next.js static import support:** `<SmartNextImage>` now correctly resolves both `StaticImageData` and `StaticRequire` import types.
|
|
167
|
+
- **Subpath exports:** Added `react-a11y-auto-caption/next` entry point for cleaner Next.js-specific imports.
|
|
168
|
+
|
|
169
|
+
|
package/package.json
CHANGED