@artooi/ag-ui-web-component 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-06-26
+
+### Added
+
+- **Localization (i18n).** Every user-facing string — labels, placeholders,
+  `aria-label`s, and `title` tooltips — now reads from a flat `UiStrings` table.
+  Override any subset via the `strings` property or the `data-strings` JSON
+  attribute (the property wins key-by-key); the rest fall back to the English
+  defaults. A few keys are `{token}` templates (`minutesAgo`, `confirmRun`,
+  `tooLarge`, …). New exports: `UiStrings`, `DEFAULT_UI_STRINGS`,
+  `mergeUiStrings`.
+- **`::part()` styling and replaceable slots.** Every structural element exposes
+  a stable `part` (`panel`, `header`, `title`, `messages`, `tool-card`,
+  `composer`, `input`, `send`, `launcher`, the drawer parts, …) so hosts restyle
+  from outside the Shadow DOM without piercing it. Coarse slots — `icon`,
+  `header-actions`, `empty`, `footer`, `launcher` — replace whole regions with
+  host markup.
+- **Header / launcher icon.** An `icon` slot (any markup) before the title, or
+  the `data-icon-url` attribute convenience (an `<img>`); the slot wins. Sized
+  via `--ag-ui-icon-size`.
+- **Sidebar placement.** `placement="sidebar"` is a full-height docked panel
+  that slides open/closed and collapses to a slim icon **rail** (instead of the
+  floating launcher). Docks right by default; `data-side="left"` docks left.
+  Overlays by default (`--ag-ui-position: static` for host-managed push); the
+  slide honours `prefers-reduced-motion`; the rail carries `aria-expanded`.
+- **Built-in page-action tools.** Opt in via `data-page-actions` (a comma list of
+  `scroll` / `drag`): `scroll_to` (a target into view — `top` / `bottom` / a
+  selector or page-map id) and `drag_and_drop` (fires the native HTML5 drag
+  sequence so the page's own drop handler reacts). Targets resolve through the
+  overridable `resolvePageTarget` property. Not stamped destructive — gate
+  auto-persist-on-drop pages with `confirmPredicate`. New exports:
+  `createPageActionTools`, `PAGE_ACTIONS`, `ResolvePageTarget`.
+
+### Fixed
+
+- **Stuck "pending" UI when the stream drops mid-run.** A run whose stream closes
+  without a terminal `RUN_FINISHED` / `RUN_ERROR` event used to resolve as if it
+  had succeeded, leaving the thinking indicator — and any in-flight tool card —
+  stuck forever. Such a close is now surfaced as a connection-loss error (the
+  localizable `connectionLost` string), and `onSettled` sweeps any tool card
+  still pending to the no-result fallback. New export: `ConnectionLostError`.
+
+## [0.6.0] — 2026-06-25
+
+### Added
+
+- **File uploads.** Set `data-attachments-url` (django-ag-ui's `AttachmentsView`)
+  to reveal a 📎 picker + drag-and-drop on the composer. Each file uploads
+  out-of-band (multipart, with the element's `headers`) into a pending tray —
+  one chip per file with a progress bar, settling to `ready` or `error` (with
+  retry / remove). On send, the ready files' refs render as read-only chips on
+  the user bubble and travel to the agent: the wire stays vanilla AG-UI (only
+  lightweight `{ id, name, mime, size }` refs, never bytes), the model learns the
+  ids from a one-line run-context manifest, and reads contents server-side via
+  the `read_attachment` tool. Refs persist on the message, so a restored
+  conversation re-renders its chips.
+- **Client-side guards** (instant feedback; the server stays authoritative):
+  `data-attachment-accept` (an `<input accept>` list) and
+  `data-attachment-max-bytes` (default 10 MiB, `0` disables).
+- **Pluggable upload transport.** A new `uploadHandler` property —
+  `(file, onProgress) => Promise<AttachmentRef>` — swaps the built-in multipart
+  upload for a custom one (a resumable `tus-js-client` adapter, direct-to-S3
+  multipart, …) without touching the tray, chips, or AG-UI wire. When set, the
+  📎 affordance appears even with no `data-attachments-url`. Defaults to the
+  built-in `uploadAttachment`.
+- **New exports:** `uploadAttachment` + `UploadOptions` + `UploadHandler`, the
+  `AttachmentRef` type, and `messageAttachments`. `AgUiClient.send` gains an
+  optional second `attachments` argument; the `ag-ui-submit` event `detail` now
+  also carries `attachments`.
+
 ## [0.5.0] — 2026-06-24
 
 ### Added
@@ -269,7 +339,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.3.0...v0.3.1

package/README.md

@@ -44,6 +44,7 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
   - [Registering tools](#registering-tools)
   - [Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)](#inline-confirmation-x-destructive--x-confirm--confirmpredicate)
   - [DOM-driver and animation primitives](#dom-driver-and-animation-primitives)
+  - [Page-action tools](#page-action-tools)
 - [New chat and collapse](#new-chat-and-collapse)
 - [Tool-call display modes](#tool-call-display-modes)
 - [Markdown rendering](#markdown-rendering)
@@ -52,6 +53,7 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [Host seams: the SPA story](#host-seams-the-spa-story)
 - [Public API surface](#public-api-surface)
 - [Theming, density, and placement](#theming-density-and-placement)
+- [Internationalization (i18n)](#internationalization-i18n)
 - [Building the bundle](#building-the-bundle)
 - [Compatibility](#compatibility)
 
@@ -152,15 +154,24 @@ That's the whole integration: an `endpoint` attribute pointing at your AG-UI ser
 | `data-skills` | — | Inline JSON skill catalog. |
 | `data-skills-url` | — | URL of a JSON skill catalog (fetched with `headers`). |
 | `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with `headers`; labels tool-call cards for server-side tools. |
-| `collapsed` | `collapsed` | Reflected boolean; collapses the widget. Persisted per-tab in `sessionStorage`. |
+| `data-threads-url` | — | URL of a server thread index (django-ag-ui's `ThreadsView`); enables durable, cross-device chat history. |
+| `data-attachments-url` | — | URL of the file-upload endpoint (django-ag-ui's `AttachmentsView`); reveals the composer's 📎 picker + drag-and-drop. |
+| `data-attachment-accept` | — | `<input accept>` list for client-side type filtering (e.g. `image/*,.pdf`). The server stays authoritative. |
+| `data-attachment-max-bytes` | — | Client-side upload size cap in bytes (default 10 MiB; `0` disables). The server stays authoritative. |
+| `data-strings` | `strings` | Partial JSON override of the UI string table (localization). The property wins key-by-key over the attribute; see [Internationalization](#internationalization-i18n). |
+| `data-icon-url` | — | Header (and sidebar-rail) icon image URL. A slotted `slot="icon"` wins; see [Header & launcher icon](#header-and-launcher-icon). |
+| `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
+| `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
+| `collapsed` | `collapsed` | Reflected boolean; collapses the widget (to a rail under `placement="sidebar"`). Persisted per-tab in `sessionStorage`. |
 | `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
 | `density` | — | CSS-only: `comfortable` (default) / `compact`. |
-| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `full` / `embedded`. |
+| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `embedded`. |
 
 **Properties** (JS only, not attributes): `headers`, `allowImages`, `autoConfirm`,
 `confirmPredicate`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
-`getPageMap`, `autoInjectPageMap`, `conversationStore`, `navigationResult`, `skillContext`,
-`toolSummaries`, plus the mirrors `endpoint` / `toolDisplay` / `collapsed`.
+`getPageMap`, `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `navigationResult`,
+`skillContext`, `toolSummaries`, `strings`, `resolvePageTarget`, plus the mirrors
+`endpoint` / `toolDisplay` / `collapsed`.
 
 `allowImages` (default `false`) re-enables `<img>` in rendered assistant markdown.
 It is off by default because a model-controlled image URL is fetched by the browser
@@ -325,6 +336,36 @@ register the change.
 Each takes an element the caller has already located; host packages wrap them with
 environment-aware lookups (e.g. "find `#id_<name>`, then `fillField`").
 
+### Page-action tools
+
+Two built-in client tools let the agent perform common page interactions without every host
+re-implementing them. They are **opt-in** via `data-page-actions` — a comma list of the tokens you
+want — so you control the agent's interaction surface:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-page-actions="scroll,drag"></ag-ui-chat>
+```
+
+- **`scroll_to`** — scroll a target into view. `target` is `"top"`, `"bottom"`, or a CSS selector
+  / page-map element id. Read-only (no confirmation).
+- **`drag_and_drop`** — drag the `from` element onto the `to` element (selectors / page-map ids),
+  firing the standard HTML5 drag sequence (`dragstart` → `dragenter`/`dragover`/`drop` → `dragend`)
+  so the page's own drop handler reacts. Useful for reordering sortable lists.
+
+Targets resolve through the overridable `resolvePageTarget` property — `(target) => HTMLElement |
+null`, defaulting to `document.querySelector`. A host with a page map overrides it to map its own
+element ids (the same way the DOM-driver primitives are wrapped with environment-aware lookups):
+
+```js
+chat.resolvePageTarget = (id) => myPageMap.elementFor(id);
+```
+
+**Destructiveness.** Page actions are *not* stamped `x-destructive` — a drag rearranges transient
+state, and the durable change happens at the page's explicit commit (a Save), which stays in the
+user's hands. If your page persists *on drop* (a kanban board firing a PATCH from the drop
+handler), gate `drag_and_drop` with [`confirmPredicate`](#inline-confirmation-x-destructive--x-confirm--confirmpredicate)
+— or don't enable it. A target that resolves to nothing returns a clean, model-readable tool error.
+
 ---
 
 ## New chat and collapse
@@ -525,6 +566,57 @@ chat.navigate = (path) => router.push(path); // SPA: in-page, no reload
 
 Route map + `navigate()` and the reload model are the same feature seen from two ends.
 
+## File uploads
+
+Set **`data-attachments-url`** (django-ag-ui's `AttachmentsView`) to let the user attach files
+to a message. A 📎 button and drag-and-drop appear on the composer; each picked file uploads
+out-of-band (multipart, with the element's `headers`) and shows a chip in a pending tray —
+`uploading` (with a progress bar) → `ready`, or `error` with a retry. On send, the ready files'
+**refs** ride on the user bubble as read-only chips and the agent reads their contents
+server-side via the `read_attachment` tool. The wire stays vanilla AG-UI: only lightweight refs
+(`{ id, name, mime, size }`) travel, never the bytes.
+
+```html
+<ag-ui-chat
+  endpoint="/agent/"
+  data-attachments-url="/agent/attachments/"
+  data-attachment-accept="image/*,application/pdf,text/plain"
+  data-attachment-max-bytes="10485760"
+></ag-ui-chat>
+```
+
+Client-side `accept` / size checks are an instant-feedback nicety — **the server is
+authoritative**. Refs persist on the message, so a restored conversation re-renders its chips.
+Without the attribute the affordance stays hidden and the chat is text-only.
+
+**Swapping the upload transport.** The built-in multipart `POST` is just the default
+`uploadHandler`. Set your own to use a different transport — a resumable
+[`tus-js-client`](https://github.com/tus/tus-js-client) adapter, direct-to-S3 multipart, etc.
+— without touching the tray, the chips, or the AG-UI wire (refs are transport-agnostic). The
+handler is `(file, onProgress) => Promise<AttachmentRef>`; when set, the 📎 affordance appears
+even with no `data-attachments-url`, and your handler owns its own endpoint and headers:
+
+```js
+import { Upload } from "tus-js-client";
+
+chat.uploadHandler = (file, onProgress) =>
+  new Promise((resolve, reject) => {
+    const up = new Upload(file, {
+      endpoint: "/tus/",
+      headers: chat.headers,
+      onProgress: (sent, total) => onProgress(sent / total),
+      onError: reject,
+      onSuccess: () =>
+        resolve({ id: up.url.split("/").pop(), name: file.name, mime: file.type, size: file.size }),
+    });
+    up.start();
+  });
+```
+
+The server side is the matching half: the agent reads bytes by ref id, so point the
+`read_attachment` store at wherever your transport persisted them (django-ag-ui's
+`AttachmentStore` is the seam). The refs themselves never change shape.
+
 ---
 
 ## Public API surface
@@ -549,6 +641,7 @@ re-export point. Internal modules import from leaf paths.
 | `AgUiClient` | class | Orchestration layer over an AG-UI `AbstractAgent`. |
 | `AgUiClientConfig` / `AgUiClientHandlers` / `AgUiRunInputs` | type | Client config, lifecycle handlers, per-run input providers. |
 | `AgUiToolCall` / `ToolExecution` / `ExecuteTool` | type | Tool-call shape, execution result, executor signature. |
+| `ConnectionLostError` | class | Raised (→ `onError`) when a run's stream closes with no terminal AG-UI event. |
 | `createHttpAgent(options)` | function | Default agent factory (wraps `HttpAgent`). |
 | `AgentFactory` / `HttpAgentOptions` | type | Factory signature and its options. |
 
@@ -560,6 +653,9 @@ re-export point. Internal modules import from leaf paths.
 | `ClientTool` | type | A frontend tool declaration. |
 | `isDestructive(parameters)` | function | Read the `x-destructive` flag. |
 | `isNavigates(parameters)` | function | Read the `x-navigates` flag. |
+| `createPageActionTools(enabled, resolveTarget)` | function | Build the opt-in `scroll_to` / `drag_and_drop` tools. |
+| `PAGE_ACTIONS` | const | The page-action opt-in tokens (`scroll` / `drag`). |
+| `ResolvePageTarget` | type | `(target) => HTMLElement | null` — the page-target resolver. |
 | `X_DESTRUCTIVE_KEY` / `X_NAVIGATES_KEY` | const | The JSON-Schema extension keys. |
 
 ### Host seams
@@ -580,9 +676,21 @@ re-export point. Internal modules import from leaf paths.
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `SessionStorageStore` | class | Default per-tab conversation store. |
+| `RemoteConversationStore` | class | Server-backed store over a `data-threads-url` endpoint. |
 | `ClientConversationStore` | type | The persistence seam. |
+| `ThreadMeta` | type | A thread-drawer row (`{ threadId, title, updatedAt, preview }`). |
 | `NavigationCheckpoint` | type | The pre-reload checkpoint marker. |
 
+### Attachments
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `uploadAttachment(file, options)` | function | The built-in upload (multipart, progress) → `AttachmentRef`. |
+| `UploadOptions` | type | `{ url, headers?, onProgress?, signal? }`. |
+| `UploadHandler` | type | `(file, onProgress) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (TUS / S3). |
+| `AttachmentRef` | type | The durable upload ref (`{ id, name, mime, size, url? }`). |
+| `messageAttachments(message)` | function | Read the refs a restored user message carries. |
+
 ### UI & DOM primitives
 
 | Export | Kind | Summary |
@@ -591,7 +699,10 @@ re-export point. Internal modules import from leaf paths.
 | `ToolCallStatus` / `SettledStatus` / `ToolDisplayMode` | type | Card lifecycle states + display mode. |
 | `requestConfirmation(host, request, options?)` | function | Append the inline confirmation card to the transcript. |
 | `ConfirmationRequest` | type | What the card displays. |
-| `ConfirmationOptions` | type | `{ signal? }` — aborting resolves the card as declined (the Stop control's hook). |
+| `ConfirmationOptions` | type | `{ signal?, strings? }` — abort resolves the card as declined; `strings` localizes it. |
+| `UiStrings` | type | The flat table of every user-facing string. |
+| `DEFAULT_UI_STRINGS` | const | The English defaults (the override floor). |
+| `mergeUiStrings(overrides)` | function | Merge a partial override over the defaults. |
 | `renderMarkdown(text)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
 | `typeInto` / `highlightThenClick` / `pressThenClick` / `selectOption` / `toggleControl` / `scrollIntoCenterView` / `focusWithFlash` / `prefersReducedMotion` | function | Animation primitives. |
 | `fillField` / `clickElement` / `pressButton` / `selectControl` / `setControlValue` / `toggleCheckbox` | function | DOM-driver primitives. |
@@ -641,8 +752,8 @@ have to hand-tune the variables:
 
 - `theme` — `light` (default) / `dark` / `auto` (follow the OS) / `code`.
 - `density` — `comfortable` (default) / `compact`.
-- `placement` — `floating` (default) / `bottom-left` / `side` / `full` / `embedded`. `embedded`
-  drops the fixed positioning and z-index so the widget sits in normal document flow.
+- `placement` — `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `embedded`.
+  `embedded` drops the fixed positioning and z-index so the widget sits in normal document flow.
 
 ```html
 <ag-ui-chat endpoint="/agent/" theme="dark" density="compact" placement="side"></ag-ui-chat>
@@ -652,6 +763,96 @@ See [`src/ui/styles.ts`](src/ui/styles.ts) for the full variable + preset list.
 [`demo/`](demo/) live playground (`node demo/mock-server.mjs`) flips theme, density, placement,
 text-animation, and tool-display live from a single page.
 
+### Parts and slots
+
+For styling beyond the `--ag-ui-*` variables, every structural element exposes a `part` so you can
+reach it from outside the Shadow DOM with `::part()` — no shadow piercing. The part names are
+**public API** (additions are non-breaking; renames are breaking):
+
+```css
+ag-ui-chat::part(panel)   { border-radius: 0; }
+ag-ui-chat::part(header)  { background: #111; }
+ag-ui-chat::part(send)    { text-transform: uppercase; }
+ag-ui-chat::part(tool-card) { font-family: var(--my-mono); }
+```
+
+Available parts: `panel`, `header`, `title`, `icon`, `header-controls`, `header-button`
+(plus `history-button` / `new-button` / `collapse-button`), `messages`, `message` (plus
+`message-user` / `message-assistant`), `empty`, `pending`, `tool-card` (plus `tool-card-head` /
+`-name` / `-status` / `-args` / `-toggle` / `-result`), `confirm` (plus `confirm-body` /
+`-args` / `-actions` / `-button` / `-cancel` / `-confirm`), `composer`, `input`, `send`,
+`attach-button`, `attachment-tray`, `launcher`, `launcher-icon`, and the drawer parts
+(`drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`,
+`drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`).
+
+Coarse **slots** let you replace whole regions with your own markup (project light-DOM children
+with a matching `slot=`):
+
+| Slot | Where |
+| --- | --- |
+| `icon` | A header brand icon, before the title. |
+| `header-actions` | Extra controls between the title and the built-in buttons. |
+| `empty` | The empty-state shown before any message. |
+| `footer` | Below the composer. |
+| `launcher` | The collapsed sidebar rail's content. |
+
+```html
+<ag-ui-chat endpoint="/agent/">
+  <img slot="icon" src="/logo.svg" alt="" />
+  <button slot="header-actions" onclick="openHelp()">?</button>
+</ag-ui-chat>
+```
+
+### Header and launcher icon
+
+Give the header a brand icon with either the `icon` slot (any markup) or the `data-icon-url`
+convenience attribute (an `<img>`); the slot wins when both are set, and with neither the header
+stays icon-less. The same icon seam feeds the collapsed sidebar rail. Size it via
+`--ag-ui-icon-size` (default `22px`).
+
+```html
+<ag-ui-chat endpoint="/agent/" data-icon-url="/logo.png"></ag-ui-chat>
+```
+
+### Sidebar placement
+
+`placement="sidebar"` is a full-height **docked** panel that slides open/closed and collapses to a
+slim **icon rail** (rather than the floating launcher). It docks right by default; `data-side="left"`
+docks it left. Collapse state reuses the `collapsed` attribute (persisted per-tab), and the rail
+carries `aria-expanded`. The slide honours `prefers-reduced-motion`.
+
+```html
+<ag-ui-chat endpoint="/agent/" placement="sidebar" data-side="left"></ag-ui-chat>
+```
+
+It overlays the page by default (no host-layout coupling). To make the host content reflow around
+it instead, set `--ag-ui-position: static` and place the element in your own grid/flex layout.
+
+---
+
+## Internationalization (i18n)
+
+Every user-facing string — labels, placeholders, `aria-label`s, and `title` tooltips — is read
+from a flat `UiStrings` table, so a non-English host can translate the widget without forking it.
+Override any subset; the rest fall back to the English defaults. Two equivalent seams:
+
+```js
+// As a property (merged over the defaults):
+chat.strings = { send: "Senden", inputPlaceholder: "Frag mich…", stop: "Stopp" };
+```
+
+```html
+<!-- Or inline, as JSON (the property wins key-by-key when both are set): -->
+<ag-ui-chat endpoint="/agent/" data-strings='{"send": "Senden", "inputPlaceholder": "Frag mich…"}'></ag-ui-chat>
+```
+
+Set `strings` / `data-strings` **before** the element connects (they resolve on mount). A few keys
+are templates carrying `{token}` placeholders the widget fills in — e.g. `minutesAgo`
+(`"{n}m ago"`), `confirmRun` (`"Run “{tool}”?"`), `tooLarge` (`"Too large (max {size})"`). Keep the
+token verbatim when translating. The full key list and English defaults live in
+[`src/ui/ui_strings.ts`](src/ui/ui_strings.ts) (exported as `DEFAULT_UI_STRINGS`); `mergeUiStrings`
+is exported too if you want to compute a complete table yourself.
+
 ---
 
 ## Building the bundle