docs: update docs for bulk-ai-flow plugin

Author: yaroslav8765

adminforth/design/adoption.md

@@ -9,13 +9,13 @@ Which packages follow the [design concepts](./system-concepts.md): tokens instea
 | @adminforth/audit-log | ✓ |
 | @adminforth/auto-remove | no UI |
 | @adminforth/background-jobs | ✓ |
-| @adminforth/bulk-ai-flow | |
-| @adminforth/clone-row | |
-| @adminforth/crud-approve-plugin | |
+| @adminforth/bulk-ai-flow | ✓ |
+| @adminforth/clone-row | ✓ |
+| @adminforth/crud-approve-plugin | ✓ |
 | @adminforth/dashboard | ✓ |
 | @adminforth/email-invite | ✓ |
 | @adminforth/email-password-reset | ✓ |
-| @adminforth/foreign-inline-list | |
+| @adminforth/foreign-inline-list |  |
 | @adminforth/foreign-inline-show | |
 | @adminforth/i18n | ✓ |
 | @adminforth/i18n-static | ✓ |
@@ -63,4 +63,4 @@ The cards of the landing gallery (`documentation/src/pages/index.tsx`) show eith
 
 - If simple - get of flowbite, prefer pure AFCL + Tailwind, move features we luck to AFCL
 - Existing icon fonts apart lucide - try to get rid of them if not complex
-- Core uses only Lucide icons and `flag-icons` flags (`afcl/CountryFlag.vue`). `vue-flowbite` and `vue-heroicons` stay in `spa/package.json` while plugins import them (flowbite: bulk-ai-flow, clone-row, foreign-inline-list, inline-create, user-soft-delete, and dashboard only for `flowbite:chart-pie-solid`, the old default menu icon which stored dashboard configs may name; no plugin imports heroicons any more). After plugins rework it they should disappear.
+- Core uses only Lucide icons and `flag-icons` flags (`afcl/CountryFlag.vue`). `vue-flowbite` and `vue-heroicons` stay in `spa/package.json` while plugins import them (flowbite: foreign-inline-list, inline-create, user-soft-delete, and dashboard only for `flowbite:chart-pie-solid`, the old default menu icon which stored dashboard configs may name; no plugin imports heroicons any more). After plugins rework it they should disappear.

documentation/docs/tutorial/09-Plugins/17-bulk-ai-flow.md

@@ -187,14 +187,13 @@ export const admin = new AdminForth({
 > ⚠️ Make sure your attachFiles function returns a valid array of image URLs or an empty array. Returning anything else may cause an error.
 
 ## Usage
-1. Select fields you want to fill
+1. Select records you want to fill
 2. Click on the three dots menu
-3. Click analyze 
+3. Click the action
 ![alt text](Bulk-vision-1.png)
-4. Wait for finish analyze
-5. Check and edit result
+4. Wait while AI fills the records. The list on the left shows the status of every record, the record on the right shows the current value of each field next to the generated one. You can edit a generated value, regenerate one field or the whole record, or uncheck a record to skip it. `All`, `Changed` and `Failed` filter the list, `↑` and `↓` move between records and `Space` includes or skips the selected one.
 ![alt text](Bulk-vision-2.png)
-6. Save changhes
+5. Click `Save`, only the checked records are saved
 ![alt text](Bulk-vision-3.png)
 
 
@@ -346,24 +345,12 @@ new ImageGenerationAdapterOpenAI({
 
 ## Comparing new and old images
 
-If you want to compare a generated image with an image stored in your storage, you need to add the preview prop in your upload plugin setup:
-
-```ts
-  new UploadPlugin({
-        ...
-    //diff-add
-    preview: {
-    //diff-add
-      previewUrl: ({filePath}) => `https://static.my-domain.com/${filePath}`,
-    //diff-add
-    }
-        ...
-  })
-```
-After generation, you’ll see a button labeled "old image". Clicking it will open a pop-up where you can compare the generated image with the stored one:
+For an image field the review shows the stored image next to the generated one, a click opens an image in full size:
 
 ![alt text](Bulk-vision-4.png)
 
+The link to the stored image comes from the Upload plugin of the column, the same way as its own previews: `preview.previewUrl` when it is set, otherwise a link of the storage adapter.
+
 ## Extra data fields
 
 When creating default prompts, you can use Handlebars to pass data from the record into the prompt:
@@ -407,12 +394,12 @@ askConfirmationBeforeGenerating: true,
 ...
 ```
 
-The user will now see a popup with a "Start generation" button and an "Edit prompts" button, allowing them to modify the prompt before running it.
+Before the generation starts, the user now sees the fields which will be generated. The pencil next to a field opens its prompt for editing. `Save prompt` keeps the edited prompt for the next runs, a prompt which is not saved (marked `Unsaved`) is used for this run only. `Reset to default` brings back the prompt from the plugin config. Here the user also chooses whether AI overwrites existing values or fills only empty fields.
 
 ![alt text](Bulk-vision-5.png)
 ![alt text](Bulk-vision-6.png)
 
-> ☝️ Updated prompts are stored in the user's local storage. Changes are local to that browser and do not affect other users or devices.
+> ☝️ Saved prompts are stored in the user's local storage. Changes are local to that browser and do not affect other users or devices.
 
 ## Processing big sets of data ( filtered records )
 
@@ -456,14 +443,14 @@ And there won't be more than 5 parallel requests being handled.
 
 ## Controlling page size in the generation dialog
 
-When users trigger bulk generation, records are displayed as cards in a paginated dialog. By default, 6 cards are shown per page. Use `pageSize` to tune this — lower values help when cards contain large images or long text, keeping the dialog fast and reviewable:
+When users trigger bulk generation, the dialog lists the records page by page, 10 records per page by default. Use `pageSize` to tune this:
 
 ```ts
 new BulkAiFlowPlugin({
   actionName: 'Generate description and Price',
 
   //diff-add
-  pageSize: 10, // default is 6
+  pageSize: 20, // default is 10
 
   // ...
 }),

documentation/docs/tutorial/09-Plugins/Bulk-vision-2.png

@@ -172,7 +172,7 @@ const images: GalleryItem[] = [
     description: 'Export tables to CSV and import from CSV with one click. Move data between environments easily'
   },
   {
-    original: require('@site/static/img/previews/bulk-ai-flow.png').default,
+    preview: 'bulk-ai-flow',
     title: 'Bulk AI Plugin - generate data for your resources',
     link: '/docs/tutorial/Plugins/bulk-ai-flow/',
     description: 'Use LLMs to fill records with generated data or images. For example, generate product descriptions based on product name and image or generate products images'

documentation/docs/tutorial/09-Plugins/Bulk-vision-4.png

@@ -0,0 +1,103 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Bulk AI flow</title>
+<link rel="stylesheet" href="previews.css">
+<style>
+  .scrim { position: absolute; inset: 0; background: var(--scrim); display: flex; align-items: center; justify-content: center; }
+  .dlg { width: 800px; background: var(--surface); border-radius: 12px; box-shadow: var(--shadow-pop); overflow: hidden; }
+  .dlg-head { display: flex; align-items: center; justify-content: space-between; padding: 14px 18px 8px; font-size: 15px; font-weight: 600; }
+  .dlg-head .i { color: var(--muted); }
+  .dlg-body { display: flex; flex-direction: column; gap: 10px; padding: 4px 18px 14px; }
+  .dlg-foot { display: flex; justify-content: flex-end; gap: 8px; padding: 10px 18px; border-top: 1px solid var(--border); background: var(--bg); }
+  .prog { display: flex; align-items: center; gap: 10px; font-size: 13px; }
+  .prog .bar { flex: 1; }
+  .ok { color: var(--success); }
+  .err { color: var(--danger-fg); }
+  .md { display: grid; grid-template-columns: 240px 1fr; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+  .rows { border-right: 1px solid var(--border); background: var(--bg); }
+  .row { display: grid; grid-template-columns: 16px 34px 1fr 16px; align-items: center; gap: 8px; padding: 8px 10px; border-bottom: 1px solid var(--border); border-left: 2px solid transparent; }
+  .row.is-on { background: var(--accent-soft); border-left-color: var(--accent); }
+  .row img { width: 34px; height: 24px; border-radius: 4px; object-fit: cover; }
+  .row b { display: block; font-size: 12.5px; font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .row span { display: block; font-size: 11px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .row .cb:checked { display: grid; }
+  .rec-head { display: flex; align-items: center; gap: 8px; padding: 9px 14px; border-bottom: 1px solid var(--border); }
+  .rec-head b { font-size: 13px; font-weight: 600; }
+  .rec-head .t-xs { display: block; }
+  .field { padding: 8px 14px; border-bottom: 1px solid var(--border); }
+  .field:last-child { border-bottom: 0; }
+  .field-head { display: flex; align-items: center; gap: 6px; margin-bottom: 6px; font-size: 12.5px; font-weight: 500; }
+  .field-head .i { margin-left: auto; color: var(--muted); }
+  .badge-new { background: var(--accent-soft); border-color: var(--accent-line); color: var(--accent-fg); height: 18px; font-size: 11px; }
+  .pair { display: grid; grid-template-columns: 1fr 14px 1fr; gap: 8px; align-items: start; }
+  .pair > .i { width: 14px; height: 14px; margin-top: 8px; color: var(--faint); }
+  .pair.media { align-items: center; }
+  .pair.media > .i { margin-top: 0; }
+  .cur { min-height: 30px; padding: 6px 9px; border-radius: 6px; background: var(--surface-2); color: var(--muted); font-size: 12px; line-height: 17px; }
+  .gen { min-height: 30px; padding: 6px 9px; border-radius: 6px; border: 1px solid var(--border-strong); background: var(--surface); font-size: 12px; line-height: 17px; }
+  .pic { width: 100%; height: 64px; border-radius: 6px; object-fit: cover; border: 1px solid var(--border); }
+  .pic.toon { filter: saturate(1.9) contrast(1.15) brightness(1.05); }
+</style>
+</head>
+<body>
+<!-- the review of the bulk AI flow: records with their status on the left, current value next to the generated one on the right -->
+<div class="screen app" style="width: 880px; height: 550px">
+  <aside class="side rail" data-active="Apartments"></aside>
+  <div class="page">
+    <header class="topbar">
+      <span class="avatar"><svg class="i"><use href="icons.svg#user"/></svg></span>
+    </header>
+    <main class="content"></main>
+  </div>
+  <div class="scrim">
+    <div class="dlg">
+      <div class="dlg-head">Process with AI<svg class="i"><use href="icons.svg#x"/></svg></div>
+      <div class="dlg-body">
+        <div class="prog">
+          <span class="spin"></span>
+          <span class="num">5 of 8 records processed</span>
+          <div class="bar"><span style="width: 62%"></span></div>
+        </div>
+        <div class="md">
+          <div class="rows">
+            <div class="row"><input class="cb" type="checkbox" checked><img src="villa.jpg" alt=""><div><b>Villa in Sitges</b><span>2 fields changed</span></div><svg class="i ok"><use href="icons.svg#circle-check"/></svg></div>
+            <div class="row is-on"><input class="cb" type="checkbox" checked><img src="park-guell.jpg" alt=""><div><b>Loft near Park Güell</b><span>3 fields changed</span></div><svg class="i ok"><use href="icons.svg#circle-check"/></svg></div>
+            <div class="row"><input class="cb" type="checkbox" checked><img src="login-bg.jpg" alt=""><div><b>Flat in Eixample</b><span style="color: var(--danger-fg)">Rate limit exceeded</span></div><svg class="i err"><use href="icons.svg#circle-alert"/></svg></div>
+            <div class="row"><input class="cb" type="checkbox" checked><img src="villa.jpg" alt="" style="filter: hue-rotate(40deg)"><div><b>House in Girona</b><span>Generating…</span></div><span class="spin"></span></div>
+            <div class="row" style="border-bottom: 0"><input class="cb" type="checkbox" checked><img src="park-guell.jpg" alt="" style="filter: grayscale(.6)"><div><b>Studio in Gràcia</b><span>Waiting</span></div><svg class="i t-muted"><use href="icons.svg#clock"/></svg></div>
+          </div>
+          <div>
+            <div class="rec-head">
+              <div style="flex: 1"><b>Loft near Park Güell</b><span class="t-xs t-muted">Record 2 of 8</span></div>
+              <span class="btn btn-secondary btn-sm"><svg class="i i-sm"><use href="icons.svg#refresh-cw"/></svg>Regenerate</span>
+              <span class="btn btn-secondary btn-sm btn-icon"><svg class="i"><use href="icons.svg#chevron-up"/></svg></span>
+              <span class="btn btn-secondary btn-sm btn-icon"><svg class="i"><use href="icons.svg#chevron-down"/></svg></span>
+            </div>
+            <div class="field">
+              <div class="field-head">Description <span class="badge badge-new">New</span><svg class="i i-sm"><use href="icons.svg#refresh-cw"/></svg></div>
+              <div class="pair"><div class="cur">-</div><svg class="i"><use href="icons.svg#arrow-right"/></svg><div class="gen">Bright loft with a balcony facing Park Güell, calm street, five minutes to the metro.</div></div>
+            </div>
+            <div class="field">
+              <div class="field-head">Square meter <span class="badge badge-new">Changed</span><svg class="i i-sm"><use href="icons.svg#refresh-cw"/></svg></div>
+              <div class="pair"><div class="cur num">47</div><svg class="i"><use href="icons.svg#arrow-right"/></svg><div class="gen num">62</div></div>
+            </div>
+            <div class="field">
+              <div class="field-head">Processed image <span class="badge badge-new">Changed</span><svg class="i i-sm"><use href="icons.svg#refresh-cw"/></svg></div>
+              <div class="pair media"><img class="pic" src="park-guell.jpg" alt=""><svg class="i"><use href="icons.svg#arrow-right"/></svg><img class="pic toon" src="park-guell.jpg" alt=""></div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="dlg-foot">
+        <span class="btn btn-secondary">Cancel</span>
+        <span class="btn btn-secondary">Save processed (5)</span>
+        <span class="btn btn-primary is-disabled">Save 8 records</span>
+      </div>
+    </div>
+  </div>
+</div>
+<script src="previews.js"></script>
+</body>
+</html>