react-a11y-auto-caption 1.1.3 → 1.1.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.
- package/README.md +196 -170
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,170 +1,196 @@
|
|
|
1
|
-
# react-a11y-auto-caption
|
|
2
|
-
|
|
3
|
-
> AI-powered alt text generation component for React and Next.js images.
|
|
4
|
-
> Generate captions during development, save them once, and reuse them in production for fast, accessible images.
|
|
5
|
-
|
|
6
|
-
[](https://www.npmjs.com/package/react-a11y-auto-caption)
|
|
7
|
-
[](https://opensource.org/licenses/MIT)
|
|
8
|
-
[]()
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
## Why use react-a11y-auto-caption?
|
|
12
|
-
|
|
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.
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Quick Start
|
|
22
|
-
|
|
23
|
-
### React
|
|
24
|
-
|
|
25
|
-
```tsx
|
|
26
|
-
import { SmartImage } from 'react-a11y-auto-caption';
|
|
27
|
-
|
|
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
|
-
```
|
|
37
|
-
|
|
38
|
-
### Next.js
|
|
39
|
-
|
|
40
|
-
```tsx
|
|
41
|
-
import { SmartNextImage } from 'react-a11y-auto-caption/next';
|
|
42
|
-
import sampleImage from '../public/sample.jpg';
|
|
43
|
-
|
|
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
|
-
}
|
|
54
|
-
```
|
|
55
|
-
> **Optional**: set the API endpoint once with a Provider
|
|
56
|
-
|
|
57
|
-
### Wrap your app with the Provider (Optional but Recommended)
|
|
58
|
-
|
|
59
|
-
Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
|
|
60
|
-
|
|
61
|
-
```tsx
|
|
62
|
-
// App.tsx or layout.tsx
|
|
63
|
-
import { SmartImageProvider } from "react-a11y-auto-caption";
|
|
64
|
-
|
|
65
|
-
export default function App({ children }) {
|
|
66
|
-
return (
|
|
67
|
-
<SmartImageProvider value={{ apiEndpoint: "https://your-api.com/api/generate-caption" }}>
|
|
68
|
-
{children}
|
|
69
|
-
</SmartImageProvider>
|
|
70
|
-
);
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## Installation
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
# npm
|
|
80
|
-
npm install react-a11y-auto-caption
|
|
81
|
-
|
|
82
|
-
# yarn
|
|
83
|
-
yarn add react-a11y-auto-caption
|
|
84
|
-
|
|
85
|
-
# pnpm
|
|
86
|
-
pnpm add react-a11y-auto-caption
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
---
|
|
90
|
-
## Recommended workflow
|
|
91
|
-
|
|
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
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## API Reference
|
|
100
|
-
|
|
101
|
-
Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
|
|
102
|
-
|
|
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
|
-
| `lazyGenerate` | `boolean` | `true` | Delays AI API calls until the image enters the viewport using `IntersectionObserver`.|
|
|
109
|
-
| `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Recommended for testing. |
|
|
110
|
-
| `announceLive` | `boolean` | `false` | Enables `aria-live` region to announce generation status to screen readers. |
|
|
111
|
-
| `onCaptionGenerated` | `(caption: string) => void` | `undefined` | Callback fired when a caption is successfully generated. |
|
|
112
|
-
| `onCaptionError` | `(error: Error) => void` | `undefined` | Callback fired when caption generation fails. Use for logging or toast notifications. |
|
|
113
|
-
|
|
114
|
-
> **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
|
|
115
|
-
|
|
116
|
-
---
|
|
117
|
-
|
|
118
|
-
## Error Handling
|
|
119
|
-
|
|
120
|
-
You can handle errors in two ways depending on your use case.
|
|
121
|
-
|
|
122
|
-
**Via callback** — for external handling like logging or toasts:
|
|
123
|
-
|
|
124
|
-
```tsx
|
|
125
|
-
<SmartImage
|
|
126
|
-
src={imageUrl}
|
|
127
|
-
onCaptionError={(err) => toast.error(err.message)}
|
|
128
|
-
/>
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
**Via `useAICaptions` hook** — for UI branching:
|
|
132
|
-
|
|
133
|
-
```tsx
|
|
134
|
-
const { generatedAlt, isGenerating, error } = useAICaptions({ src });
|
|
135
|
-
|
|
136
|
-
if (error) return <p>Failed to generate caption.</p>;
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
---
|
|
140
|
-
|
|
141
|
-
##
|
|
142
|
-
|
|
143
|
-
This package
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
1
|
+
# react-a11y-auto-caption
|
|
2
|
+
|
|
3
|
+
> AI-powered alt text generation component for React and Next.js images.
|
|
4
|
+
> Generate captions during development, save them once, and reuse them in production for fast, accessible images.
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/react-a11y-auto-caption)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[]()
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
## Why use react-a11y-auto-caption?
|
|
12
|
+
|
|
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.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Quick Start
|
|
22
|
+
|
|
23
|
+
### React
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { SmartImage } from 'react-a11y-auto-caption';
|
|
27
|
+
|
|
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
|
+
```
|
|
37
|
+
|
|
38
|
+
### Next.js
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
import { SmartNextImage } from 'react-a11y-auto-caption/next';
|
|
42
|
+
import sampleImage from '../public/sample.jpg';
|
|
43
|
+
|
|
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
|
+
}
|
|
54
|
+
```
|
|
55
|
+
> **Optional**: set the API endpoint once with a Provider
|
|
56
|
+
|
|
57
|
+
### Wrap your app with the Provider (Optional but Recommended)
|
|
58
|
+
|
|
59
|
+
Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
// App.tsx or layout.tsx
|
|
63
|
+
import { SmartImageProvider } from "react-a11y-auto-caption";
|
|
64
|
+
|
|
65
|
+
export default function App({ children }) {
|
|
66
|
+
return (
|
|
67
|
+
<SmartImageProvider value={{ apiEndpoint: "https://your-api.com/api/generate-caption" }}>
|
|
68
|
+
{children}
|
|
69
|
+
</SmartImageProvider>
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# npm
|
|
80
|
+
npm install react-a11y-auto-caption
|
|
81
|
+
|
|
82
|
+
# yarn
|
|
83
|
+
yarn add react-a11y-auto-caption
|
|
84
|
+
|
|
85
|
+
# pnpm
|
|
86
|
+
pnpm add react-a11y-auto-caption
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
## Recommended workflow
|
|
91
|
+
|
|
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
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## API Reference
|
|
100
|
+
|
|
101
|
+
Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
|
|
102
|
+
|
|
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
|
+
| `lazyGenerate` | `boolean` | `true` | Delays AI API calls until the image enters the viewport using `IntersectionObserver`.|
|
|
109
|
+
| `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Recommended for testing. |
|
|
110
|
+
| `announceLive` | `boolean` | `false` | Enables `aria-live` region to announce generation status to screen readers. |
|
|
111
|
+
| `onCaptionGenerated` | `(caption: string) => void` | `undefined` | Callback fired when a caption is successfully generated. |
|
|
112
|
+
| `onCaptionError` | `(error: Error) => void` | `undefined` | Callback fired when caption generation fails. Use for logging or toast notifications. |
|
|
113
|
+
|
|
114
|
+
> **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Error Handling
|
|
119
|
+
|
|
120
|
+
You can handle errors in two ways depending on your use case.
|
|
121
|
+
|
|
122
|
+
**Via callback** — for external handling like logging or toasts:
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
<SmartImage
|
|
126
|
+
src={imageUrl}
|
|
127
|
+
onCaptionError={(err) => toast.error(err.message)}
|
|
128
|
+
/>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**Via `useAICaptions` hook** — for UI branching:
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
const { generatedAlt, isGenerating, error } = useAICaptions({ src });
|
|
135
|
+
|
|
136
|
+
if (error) return <p>Failed to generate caption.</p>;
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Backend Integration
|
|
142
|
+
|
|
143
|
+
This package needs a caption API endpoint to generate alt text.
|
|
144
|
+
|
|
145
|
+
The easiest way is to run the official local server:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npx react-a11y-auto-caption-server
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
By default, the server runs at:
|
|
152
|
+
|
|
153
|
+
```txt
|
|
154
|
+
http://127.0.0.1:8000/api/generate-caption
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Use it with `SmartImage` or `SmartNextImage`:
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
<SmartImage
|
|
161
|
+
src="/example.jpg"
|
|
162
|
+
apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
|
|
163
|
+
/>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
You can also change the port:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
npx react-a11y-auto-caption-server --port 5000
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Then update the endpoint:
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
<SmartImage
|
|
176
|
+
src="/example.jpg"
|
|
177
|
+
apiEndpoint="http://127.0.0.1:5000/api/generate-caption"
|
|
178
|
+
/>
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
> First run may take a few minutes because the server creates a Python environment and installs AI dependencies.
|
|
182
|
+
|
|
183
|
+
For production, we recommend running your own caption server and applying CORS restrictions, file size limits, and rate limiting.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## What's New in v1.0.4
|
|
188
|
+
|
|
189
|
+
- **LRU Cache:** Replaced unbounded `Map` cache with an LRU implementation to prevent memory leaks in long-running apps.
|
|
190
|
+
- **`onCaptionError` callback:** New prop to handle caption generation failures externally (e.g. logging, toast notifications).
|
|
191
|
+
- **`error` state:** `useAICaptions` hook now returns an `error` field so you can branch your UI on failure.
|
|
192
|
+
- **Unmount safety:** Caption generation is now safely cancelled when a component unmounts, preventing stale state updates.
|
|
193
|
+
- **Next.js static import support:** `<SmartNextImage>` now correctly resolves both `StaticImageData` and `StaticRequire` import types.
|
|
194
|
+
- **Subpath exports:** Added `react-a11y-auto-caption/next` entry point for cleaner Next.js-specific imports.
|
|
195
|
+
|
|
196
|
+
|
package/package.json
CHANGED