@uploadcare/ai-enhancer 0.1.1 → 0.1.2

package/README.md

@@ -1,314 +1,128 @@
-# @uploadcare/ai-enhancer
+<p align="center">
+  <a href="https://uploadcare.com/?ref=ai-enhancer">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="https://ucarecdn.com/3b610a0a-780c-4750-a8b4-3bf4a8c90389/logotransparentinverted.svg">
+      <img width=250 alt="Uploadcare logo" src="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg">
+    </picture>
+  </a>
+</p>
+<p align="center">
+  <a href="https://uploadcare.com/?ref=ai-enhancer">Website</a> •
+  <a href="https://uploadcare.github.io/ai-enhancer/">Docs</a> •
+  <a href="https://uploadcare.com/blog?ref=ai-enhancer">Blog</a> •
+  <a href="https://twitter.com/Uploadcare?ref=ai-enhancer">Twitter</a>
+</p>
+
+# Uploadcare AI Enhancer
+
+[![NPM version][npm-img]][npm-url]
+[![Build Status][badge-build]][build-url]
+[![GitHub release][badge-release-img]][badge-release-url]
 
 AI image generation and editing for [Uploadcare](https://uploadcare.com/) — a
-framework-agnostic `<uc-ai-enhancer>` web component, plus an optional plugin that
-adds an **AI Edit** action and a **Generate image** source to the
+framework-agnostic `<uc-ai-enhancer>` web component, plus an optional plugin
+that adds an **AI Edit** action and a **Generate image** source to the
 [Uploadcare File Uploader](https://uploadcare.com/docs/file-uploader/). Generate
-images from a text prompt, edit existing ones by uuid, pick aspect ratios, and
-commit the result back as an already-uploaded Uploadcare file.
+images from a text prompt, edit existing ones by uuid, and commit the result
+back as an already-uploaded Uploadcare file.
 
-```sh
-npm install @uploadcare/ai-enhancer
-# or
-pnpm add @uploadcare/ai-enhancer
-yarn add @uploadcare/ai-enhancer
-```
-
-Two entry points, imported independently so you only pull in what you use:
-
-| Import | What it gives you |
-|---|---|
-| `@uploadcare/ai-enhancer` | Registers the `<uc-ai-enhancer>` element and exports its public types, the provider, and the localization helpers. |
-| `@uploadcare/ai-enhancer/plugin` | Just the `AiEnhancerPlugin` for the File Uploader — no eager component registration. |
-
-> The plugin entry needs `@uploadcare/file-uploader` **≥ 1.31.2** as a
-> peer dependency (it relies on `uploaderApi.replaceFile`). The standalone editor
-> has no peer dependency.
-
-You need an Uploadcare **public key** (from the
-[dashboard](https://app.uploadcare.com/)) to generate or edit images.
-
-## Use as a File Uploader plugin
-
-Register the plugin on `<uc-config>` and add `ai-enhancer` to the source list.
-The plugin reads its settings (public key, CDN config, locale, …) straight from
-the uploader config — there's nothing extra to wire up.
-
-```ts
-import * as UC from '@uploadcare/file-uploader'
-import { AiEnhancerPlugin } from '@uploadcare/ai-enhancer/plugin'
+## Quick start
 
-UC.defineComponents(UC)
+1. Install the package:
 
-const config = document.querySelector('uc-config')
-config.plugins = [AiEnhancerPlugin]
-```
-
-```html
-<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
-<uc-config
-  ctx-name="my-uploader"
-  pubkey="YOUR_PUBLIC_KEY"
-  source-list="local, url, camera, ai-enhancer"
-></uc-config>
-<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>
+```bash
+npm install @uploadcare/ai-enhancer
 ```
 
-The plugin contributes two affordances:
-
-- **Generate image** — an upload source (shown because `ai-enhancer` is in
-  `source-list`). Opens the editor in generate mode; the committed result is
-  **added** as a new file (sourced to `ai-enhancer`).
-- **AI Edit** — a file action on already-uploaded images. Opens the editor in
-  edit mode on that image; the committed result **replaces the original entry in
-  place** (same list position; the entry gets a new `internalId`) and keeps the
-  original file's name.
-
-### Configuration
-
-The plugin consumes these `<uc-config>` keys (all standard uploader config — set
-them as attributes or properties):
+2. Use the [standalone editor][docs-getting-started] — importing the package
+registers the element; configure it via [properties][docs-api] and pick a
+[layout][docs-layout], [theme][docs-theming], and [locale][docs-l10n]:
 
-| Key | Required | Purpose |
-|---|---|---|
-| `pubkey` | ✅ | Uploadcare public key. Without it the editor is disabled. |
-| `baseUrl` | | Upload API base URL (defaults to the SDK default). |
-| `cdnCname` | | CDN cname for resolving results. |
-| `cdnCnamePrefixed` | | Base domain for public-key-prefixed CDN URLs. |
-| `cropPreset` | | Reused to derive the editor's offered aspect ratios. |
-| `metadata` | | Key/value metadata attached to the AI result, like a regular upload. A `MetadataCallback` is resolved against the source entry in edit mode; in generate mode (no input file) only the static object form applies. |
-| `localeName` | | Drives the editor language (lazy-loaded; see [Localization](#localization)). |
-| `localeDefinitionOverride` | | Per-locale string overrides, layered onto the editor's built-ins. |
-| `secureDeliveryProxyUrlResolver` | | Signs/proxies the CDN URLs the editor renders (secure delivery). |
-| `useAiEditor` | | Plugin option (mirrors `useCloudImageEditor`). Show the **AI Edit** file action (default `true`). Set `false` / `use-ai-editor="false"` to hide it. |
-
-Importing the plugin augments the uploader's config types, so `useAiEditor`
-is type-checked on `<uc-config>` (reference `@uploadcare/ai-enhancer/plugin`
-types if your project doesn't pick it up automatically).
-
-> **Already-edited images:** the AI Edit action hides itself for images that
-> already carry CDN modifiers (e.g. edited with the Cloud Image Editor) — AI Edit
-> works on the original file and can't carry those modifiers over.
-
-## Use the standalone editor
-
-`<uc-ai-enhancer>` works without the uploader. Importing the package registers the
-element; configure it via attributes/properties and listen for `uc:*` events.
-
-```ts
-import '@uploadcare/ai-enhancer'
+```js
+import '@uploadcare/ai-enhancer';
 ```
 
 ```html
 <uc-ai-enhancer pubkey="YOUR_PUBLIC_KEY"></uc-ai-enhancer>
 ```
 
-```ts
-const editor = document.querySelector('uc-ai-enhancer')
-
-editor.addEventListener('uc:done', (e) => {
-  const { uuid, cdnUrl, file } = e.detail // file: UploadcareFile
-  // persist / display the committed result…
-})
-editor.addEventListener('uc:cancel', () => {/* closed without committing */})
-editor.addEventListener('uc:error', (e) => console.warn(e.detail.error))
-
-// Edit an existing image instead of generating from scratch:
-editor.sourceUuid = 'c2499162-eb07-4b93-b31e-94a89a47e858'
-```
-
-**No bundler?** Load it from a CDN — [esm.run](https://esm.run) bundles the
-dependencies, and lazy-loaded locales resolve from the same CDN automatically
-(pin a version in production):
-
-```html
-<script type="module">
-  import 'https://esm.run/@uploadcare/ai-enhancer@0.1.0'
-</script>
-<uc-ai-enhancer pubkey="YOUR_PUBLIC_KEY" locale-name="de"></uc-ai-enhancer>
-```
-
-### `<uc-ai-enhancer>` properties
-
-| Property | Attribute | Type | Description |
-|---|---|---|---|
-| `pubkey` | `pubkey` | `string` | Uploadcare public key. Required to enable generate/edit. |
-| `sourceUuid` | `source-uuid` | `string \| null` | UUID of an image to edit. Absent → generate mode. Use either this or `sourceFileInfo`, not both. |
-| `sourceFileInfo` | — | `UploadcareFile` | Property only. The source image as an `UploadcareFile` (e.g. the object returned by `@uploadcare/upload-client`, or the `fileInfo` of a File Uploader output entry). An alternative to `sourceUuid` that hands the editor the file directly instead of having it look it up from the uuid. |
-| `outputFilename` | — | `string \| (originalFilename, counter) => string` | Property only. Names the result. A string is used verbatim; a function receives the source's original filename (`undefined` when generating from scratch) and the 1-based history counter (first is `1`). Unset → keep the source's original name. |
-| `baseUrl` | `base-url` | `string` | Upload API base URL. |
-| `cdnCname` | `cdn-cname` | `string` | CDN cname for resolving results. |
-| `cdnCnamePrefixed` | `cdn-cname-prefixed` | `string` | Base domain for prefixed CDN URLs. |
-| `aspectRatios` | `aspect-ratios` | `AspectRatio[] \| null` | Ratios offered in generate mode, e.g. `aspect-ratios="16:9 5:4 1:1"`. Empty → popular set. |
-| `presetsOnly` | `presets-only` | `boolean` | Hide the free-text prompt; preset chips only, and picking one generates immediately. |
-| `presets` | — | `AiPresets` | Property only. Quick-prompt chips keyed by mode, e.g. `{ generate: [{ label, prompt }], edit: [...] }`. Clicking a chip fills the prompt. Modes left out use the built-in set; an empty array (`{ generate: [] }`) hides that mode's chips. Keyed by mode, so future modes extend it without breaking existing configs. |
-| `metadata` | — | `Metadata \| MetadataCallback \| null` | Property only. Same shape as the file uploader's `metadata` config: a static key/value bag (`Record<string, string>`, e.g. `{ source: 'ai-enhancer' }`) or a `MetadataCallback` the editor calls at generation time with the source file (optionally async). The callback only runs when there's a source to pass it (editing an existing image); when generating from scratch it's skipped, so use the static object form there. |
-| `composerPlacement` | `composer-placement` | `ComposerPlacement` | Which edge the composer sits on: `bottom` (default) or `top`. |
-| `canvasFit` | `canvas-fit` | `CanvasFit` | How the canvas sizes relative to the composer: `available` (default) shrinks the canvas to the space left by the composer (docked outside the image; history chips still overlay it); `full` lets the canvas fill the area with the composer floating over it. |
-| `historyPlacement` | `history-placement` | `HistoryPlacement` | Where the history strip sits: `composer-above` (default) / `composer-below` (relative to the composer) or `canvas-top` / `canvas-bottom` (pinned to the canvas edge). |
-| `composerAutoHide` | `composer-auto-hide` | `boolean` | Once an image exists, dock the composer down to a small peek; it raises when the pointer nears its edge or it gains focus. Always floats the composer, so it implies `canvas-fit="full"`. Off by default. |
-| `toolbarPlacement` | `toolbar-placement` | `ToolbarPlacement` | Where the Cancel / Done toolbar sits: `bottom` (default) or `top`. |
-| `localeName` | `locale-name` | `string` | Active locale (default `en`); the editor lazy-loads that locale's built-in strings. |
-| `localeDefinitionOverride` | — | `Record<string, Partial<AiEnhancerLocale>>` | Per-locale string overrides, keyed by locale name (see [Localization](#localization)). |
-| `secureDeliveryProxyUrlResolver` | — | `SecureDeliveryProxyUrlResolver` | Property only. Signs/proxies rendered CDN URLs. |
-
-### `<uc-ai-enhancer>` events
-
-All events bubble and are `composed`.
-
-| Event | `detail` | Fired when |
-|---|---|---|
-| `uc:done` | `DoneDetail` | The user commits a result. |
-| `uc:cancel` | — | The user closes without committing. |
-| `uc:error` | `{ error: unknown }` | A generation/edit fails. |
-
-```ts
-type DoneDetail = {
-  url: string
-  uuid: string // same as file.uuid
-  prompt: string
-  mode: 'generate' | 'edit'
-  aspectRatio?: AspectRatio
-  file: UploadcareFile // the committed result
-}
+```js
+const editor = document.querySelector('uc-ai-enhancer');
+editor.addEventListener('uc:done', (e) => console.log(e.detail.url));
 ```
 
-### Edit vs. generate mode
-
-Mode is **derived**, not set explicitly: the editor is in `edit` mode whenever
-there's a current image — an input source (`sourceUuid` / `sourceFileInfo`) or a
-generation result — and `generate` otherwise. So the first successful generation
-flips the editor into edit mode for free, and a "Start over" affordance appears
-(only for generate sessions — editing an existing source has nothing to start
-over to).
+All `uc:*` events and their payloads are listed in the [API reference][docs-api].
 
-## Framework usage
+> **Client-only:** importing the package registers custom elements, so it must
+> run in the browser — in SSR apps load it behind a client boundary (see
+> [Bundlers & SSR][docs-ssr]), or use the SSR-safe
+> [React wrapper][docs-react].
 
-`<uc-ai-enhancer>` is a standard custom element, so it works in any framework. Two
-things to wire up: object/function values (`metadata`, `presets`,
-`sourceFileInfo`, `outputFilename`, …) must be set as **DOM properties**, not
-string attributes, and `uc:*` events are plain DOM events.
-
-For **React**, install the [`@uploadcare/react-ai-enhancer`](../react-ai-enhancer)
-wrapper — typed props + `onDone` / `onCancel` / `onError` callbacks:
+Or as a [File Uploader plugin][docs-plugin], assuming a working
+[File Uploader](https://uploadcare.com/docs/file-uploader/) setup
+(`@uploadcare/file-uploader` **≥ 1.31.2**) — the plugin reads its settings
+from the uploader config:
 
 ```bash
-npm install @uploadcare/react-ai-enhancer
+npm install @uploadcare/ai-enhancer @uploadcare/file-uploader
 ```
 
-```tsx
-import { AiEnhancer } from '@uploadcare/react-ai-enhancer'
+```js
+import * as UC from '@uploadcare/file-uploader';
+import { AiEnhancerPlugin } from '@uploadcare/ai-enhancer/plugin';
 
-<AiEnhancer pubkey="YOUR_PUBLIC_KEY" onDone={(d) => console.log(d.url)} />
+UC.defineComponents(UC);
+document.querySelector('uc-config').plugins = [AiEnhancerPlugin];
 ```
 
-```vue
-<!-- Vue 3: mark `uc-` tags as custom elements (vite.config / compilerOptions),
-     then bind properties with `.prop` and events with `@`. -->
-<uc-ai-enhancer :pubkey="key" .metadata="meta" @uc:done="onDone" />
-```
-
-- **Angular** — add `CUSTOM_ELEMENTS_SCHEMA`; bind `[prop]` and `(uc:done)`.
-- **Svelte** — works natively: attributes/properties and `on:uc:done`.
-
-## Bundlers & SSR
-
-The two entry points are imported independently, so you only ship what you use,
-and the editor's styles live in its shadow DOM — there's no separate CSS import.
-
-**SSR (Next.js, Nuxt, …):** the editor is a browser web component — register it
-**client-side only** (e.g. a dynamic `import('@uploadcare/ai-enhancer')` inside an
-effect, or a `'use client'` component), never during server render.
-
-## TypeScript
-
-- Event details are typed — cast `e.detail` to `DoneDetail` (exported), or augment
-  your framework's event map.
-- Importing `@uploadcare/ai-enhancer/plugin` augments the uploader's config types
-  (`useAiEditor`, the editor's locale keys). If your project doesn't pick that up
-  automatically, reference it once: `/// <reference types="@uploadcare/ai-enhancer/plugin" />`.
-
-## Theming
-
-The editor is styled entirely through CSS custom properties on the element. When
-used as a plugin, most tokens inherit from the uploader's `--uc-*` theme
-automatically. Set any of these to customize:
-
-```css
-uc-ai-enhancer {
-  --uc-ai-primary: #6d28d9;
-  --uc-ai-radius: 20px;
-  --uc-ai-dot-grid-color: #2a2a2a;
-}
-```
-
-| Token group | Tokens |
-|---|---|
-| Color | `--uc-ai-foreground`, `--uc-ai-background`, `--uc-ai-floating`, `--uc-ai-floating-border`, `--uc-ai-muted`, `--uc-ai-muted-foreground`, `--uc-ai-primary`, `--uc-ai-primary-hover`, `--uc-ai-primary-foreground`, `--uc-ai-primary-transparent`, `--uc-ai-secondary`, `--uc-ai-secondary-hover`, `--uc-ai-secondary-foreground`, `--uc-ai-border`, `--uc-ai-destructive`, `--uc-ai-destructive-foreground` |
-| Shape | `--uc-ai-radius`, `--uc-ai-radius-button`, `--uc-ai-radius-card`, `--uc-ai-radius-frame`, `--uc-ai-radius-input` |
-| Layout & type | `--uc-ai-padding`, `--uc-ai-button-size`, `--uc-ai-font-family`, `--uc-ai-font-size` |
-| Canvas / motion | `--uc-ai-dot-grid-color`, `--uc-ai-shadow-color`, `--uc-ai-dialog-shadow`, `--uc-ai-transition`, `--uc-ai-ease-in-out`, `--uc-ai-ease-out` |
-| Prompt | `--uc-ai-prompt-max-height`, `--uc-ai-prompt-max-lines` |
-
-## Localization
-
-The editor ships English eagerly and lazy-loads 34 other locales. Set the active
-language with `localeName`; the editor loads that locale's built-in strings on
-demand. Customize individual strings with `localeDefinitionOverride` — **keyed by
-locale name**, the same shape as the file uploader's config. As a plugin, both
-follow the uploader's `localeName` / `localeDefinitionOverride` automatically.
-
-```ts
-// Standalone: pick the language and override specific strings per locale.
-editor.localeName = 'de'
-editor.localeDefinitionOverride = {
-  en: { 'ai-enhancer-cancel': 'Dismiss' },
-  de: { 'ai-enhancer-generate-btn': 'Los!' },
-}
-```
-
-Supported locales: `en ar az ca cs da de el es et fi fr he hy is it ja ka kk ko
-lv nb nl pl pt ro ru sk sr sv tr uk vi zh` (and `zh-TW`). Error-code messages
-(`ai-enhancer-error-<code>`) are optional per locale and fall back to the generic
-message. `enLocale` is exported for looking up strings outside the element.
-
-## API reference
-
-Everything below is exported from `@uploadcare/ai-enhancer` (the plugin and its
-types come from `@uploadcare/ai-enhancer/plugin`).
-
-### Plugin — `@uploadcare/ai-enhancer/plugin`
-
-- **`AiEnhancerPlugin`** — `UploaderPlugin`. Add to `config.plugins`.
-- **`AiEditorActivityParams`** — `{ sourceInternalId?: string }`. Activity params;
-  presence of `sourceInternalId` means edit mode (the source uuid + file info are
-  read from that entry, and `uc:done` replaces it in place).
-- **`aspectRatiosFromCropPreset(cropPreset: string): AspectRatio[] | null`** —
-  translate the uploader's `cropPreset` into the editor's offered ratios.
-
-### Editor
-
-- **`UcAiEnhancer`** (`<uc-ai-enhancer>`) — the editor element (see properties /
-  events above).
-- Types: **`DoneDetail`**, **`OutputFilenameResolver`** (`(originalFilename, counter) => string`),
-  **`MetadataCallback`** (`(fileInfo: UploadcareFile) => Metadata | Promise<Metadata>`),
-  **`ComposerPlacement`**, **`CanvasFit`**, **`HistoryPlacement`**,
-  **`ToolbarPlacement`**, **`AspectRatio`**, **`AiPreset`** (`{ label, prompt }`),
-  **`AiPresets`** (`Partial<Record<AiEditorMode, AiPreset[]>>`),
-  **`AiEditorMode`** (`'generate' | 'edit'`).
-
-### Localization & secure delivery
-
-- **`enLocale`**, **`AiEnhancerLocale`** — look up / type editor strings.
-- **`SecureDeliveryProxyUrlResolver`**, **`SecureDeliveryUrlParts`** — sign /
-  proxy the CDN URLs the editor renders.
-
-## Useful links
-
-- [Uploadcare File Uploader](https://uploadcare.com/docs/file-uploader/)
-- [Uploadcare CDN & transformations](https://uploadcare.com/docs/transformations/image/)
-- [Secure delivery](https://uploadcare.com/docs/security/secure-delivery/)
-
-## License
-
-MIT
+Add `ai-enhancer` to the config's `source-list` to expose the **Generate
+image** source; the **AI Edit** action appears on uploaded images
+automatically. Full setup in the [plugin guide][docs-plugin].
+
+You need an Uploadcare **public key** from the
+[dashboard](https://app.uploadcare.com/). Using React? See
+[`@uploadcare/react-ai-enhancer`][docs-react].
+
+## Documentation
+
+Everything else lives in the [docs][docs]:
+
+- [Getting started][docs-getting-started] — install, entry points, first render
+- [Integrating into your app][docs-integrating] — Vue, Angular, Svelte, bundlers, SSR
+- [File Uploader plugin][docs-plugin] — configuration and behavior
+- [UI & layout][docs-layout], [Theming][docs-theming], [Localization][docs-l10n]
+- [API reference][docs-api] — properties, events, exported types
+
+## Security issues
+
+If you think you ran into something in Uploadcare libraries that might have
+security implications, please hit us up at
+[bugbounty@uploadcare.com][uc-email-bounty] or Hackerone.
+
+We'll contact you personally in a short time to fix an issue through co-op and
+prior to any public disclosure.
+
+## Feedback
+
+Issues and PRs are welcome. You can provide your feedback or drop us a support
+request at [hello@uploadcare.com][uc-email-hello].
+
+[docs]: https://uploadcare.github.io/ai-enhancer/
+[docs-getting-started]: https://uploadcare.github.io/ai-enhancer/guide/getting-started
+[docs-integrating]: https://uploadcare.github.io/ai-enhancer/guide/integrating
+[docs-react]: https://uploadcare.github.io/ai-enhancer/guide/react
+[docs-plugin]: https://uploadcare.github.io/ai-enhancer/guide/plugin
+[docs-ssr]: https://uploadcare.github.io/ai-enhancer/guide/integrating#bundlers-ssr
+[docs-layout]: https://uploadcare.github.io/ai-enhancer/guide/layout
+[docs-theming]: https://uploadcare.github.io/ai-enhancer/guide/theming
+[docs-l10n]: https://uploadcare.github.io/ai-enhancer/guide/localization
+[docs-api]: https://uploadcare.github.io/ai-enhancer/api/
+[uc-email-bounty]: mailto:bugbounty@uploadcare.com
+[uc-email-hello]: mailto:hello@uploadcare.com
+[npm-img]: https://img.shields.io/npm/v/@uploadcare/ai-enhancer.svg
+[npm-url]: https://www.npmjs.com/package/@uploadcare/ai-enhancer
+[badge-build]: https://github.com/uploadcare/ai-enhancer/actions/workflows/checks.yml/badge.svg
+[build-url]: https://github.com/uploadcare/ai-enhancer/actions/workflows/checks.yml
+[badge-release-img]: https://img.shields.io/github/release/uploadcare/ai-enhancer.svg
+[badge-release-url]: https://github.com/uploadcare/ai-enhancer/releases