inline-chat-kit 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ The versions before 1.0 follow the pre-release convention: **a breaking change
 or new public API bumps the minor**, and the patch is for fixes. Anything that would break an
 existing install is called out under **Breaking**, with what to do about it.
 
+## 0.57.0 — 2026-09-22
+
+A pane the host draws itself. `ChatExperience` placed its artifact pane beside
+the conversation and held which one was open, which is right until the host has
+a layout of its own. Nothing changes for a host that passes none of this.
+
+### Added
+
+- **`openArtifactId` and `onOpenArtifactChange` on `ChatExperience`.** Which
+  artifact is open, held by the host. Left out, the component keeps its own;
+  `null` is a held "none open". The change callback fires either way.
+- **`pane="inline" | "none"` on `ChatExperience`.** `"none"` draws no
+  `ArtifactPane`, reserves no width for one and never calls `artifact`; a
+  pressed card only reports its id, and still shows it is open from
+  `openArtifactId`.
+- **`openArtifact(id)` and `closeArtifact()` in `renderPart`'s context**, next
+  to `turnId` — so a host's own card can open the pane. `CustomPartContext` is
+  exported. `ChatTurnRow` takes `onArtifactChange` for the same when assembled
+  by hand.
+- **`ArtifactPane` outside `ChatLayout`**, documented and tested: a region with
+  focus on its title when it mounts, no trap and no Escape unless `modal`.
+- **`surface="flush" | "panes"` on `ChatExperience` and `ChatLayout`.**
+  `"panes"` makes the conversation a card of its own, so the pane beside it —
+  the kit's or the host's — is a second surface rather than a strip cut off the
+  same one. Both are drawn from the same tokens, and `--ick-chat-pane-inset` is
+  both the ring of space around them and the gap between them. Below the
+  layout's breakpoint the corners and the inset go, where the pane is a sheet.
+  `"flush"` is the default and is what the kit drew before.
+
 ## 0.56.0 — 2026-09-22
 
 Four things that kept the kit out of a real host app: an answer could only

package/README.md

@@ -461,6 +461,10 @@ and the kit does not guess its shape.
 `ChatExperience` calls `useChatTurns` itself, so a host using it passes its own
 instead — `chat={useChatTurns({ onSend })}` — to hold `updatePart`.
 
+The second argument to `renderPart` is `{ turnId, openArtifact, closeArtifact }`
+(`CustomPartContext`), so a card can open the pane — see
+[Drawing the pane yourself](#drawing-the-pane-yourself).
+
 #### Citing a source from the prose
 
 `[^1]` in the answer is a **citation marker**, and the number is a position in
@@ -1028,6 +1032,7 @@ between products, and the only part.
 | `onOpen` | `(id: string) => void` | Without one the card is a record, not a control |
 | `<ArtifactPane>` `modal` | `boolean` | See below |
 | `<ChatLayout>` `pane` | `({ narrow }) => ReactNode` | |
+| `<ChatLayout>` `surface` | `"flush" \| "panes"` | One surface, or two. See below |
 
 **`modal` is the one prop that changes behaviour, and it is not about
 position.** Covering the conversation changes what the pane *is*: focus has to
@@ -1041,6 +1046,78 @@ That is the part worth having in a library rather than the box. On open, focus
 moves to the pane's heading — not into its first control, which would skip what
 the thing is — and it is **not** trapped unless the pane is covering the chat.
 
+#### Two panes, not one page split in half
+
+By default the conversation fills the layout and the pane is the only card on
+it — which is what a chat that owns the whole window wants. `surface="panes"`
+makes the conversation a card of its own instead:
+
+```tsx
+<ChatExperience onSend={send} surface="panes" artifact={artifact} />
+```
+
+Both surfaces are drawn from the same tokens — `--ick-chat-pane-surface` is
+`--ick-artifact-pane-surface`, and the radius follows — because two panes side
+by side have to be the same *kind* of thing, or the chat reads as the
+background and the pane as a dialog over it. One number,
+`--ick-chat-pane-inset`, is the ring of space around both and the gap between
+them, so the frame is even the whole way round. No divider: the gap is what
+says there are two of them.
+
+Below `<ChatLayout>`'s breakpoint the corners and the inset go: the pane is a
+sheet over the conversation there, and a card inside a card with a sheet over
+both is three surfaces for one screen.
+
+Inside the card, `--ick-page` is the card — so the header's tint and the fades
+at both ends end in the colour they are standing on rather than in the ground
+outside it.
+
+#### Drawing the pane yourself
+
+`ChatExperience` places the pane beside the conversation. A host with a layout
+of its own — its own column, a drawer, a route — holds which artifact is open
+and tells the kit to keep out of the way:
+
+```tsx
+const [openId, setOpenId] = useState<string | null>(null);
+const open = openId ? findArtifact(openId) : null;
+
+<div className="workspace">
+  <ChatExperience
+    chat={chat}
+    pane="none"                        // no pane here, and no room made for one
+    openArtifactId={openId}            // the cards still show which one is open
+    onOpenArtifactChange={setOpenId}   // a card pressed, or a custom card's openArtifact
+    renderPart={renderPart}
+  />
+  {open && (
+    <aside className="my-column">
+      <ArtifactPane key={openId} title={open.title} onClose={() => setOpenId(null)}>
+        {open.body}
+      </ArtifactPane>
+    </aside>
+  )}
+</div>
+```
+
+- **`openArtifactId` / `onOpenArtifactChange`** hold the state outside. Left
+  out, `ChatExperience` keeps its own, as before. `null` is a held "nothing
+  open"; only `undefined` means "not held". `onOpenArtifactChange` is called
+  either way, so a host can listen without holding.
+- **`pane="none"`** draws no `ArtifactPane`, makes no room for one and never
+  calls `artifact`. Pressing a card reports the id (pressing the open one again
+  reports `null`).
+- **A custom card opens one too.** `renderPart`'s second argument carries
+  `openArtifact(id)` and `closeArtifact()`, next to `turnId`: a caregiver in
+  your card opens her profile the way an `ArtifactCard` opens a plan.
+- **`surface="panes"` goes with it.** The conversation becomes a card, your
+  pane is the second one, and the two match without your having to copy the
+  kit's radius and shadow.
+- **`<ArtifactPane>` stands on its own.** Outside `ChatLayout` leave `modal`
+  off: it is a region, focus moves to its title when it mounts, and it neither
+  traps focus nor takes Escape. Key it by the artifact's id, so opening a
+  different one is a new pane — and focus moves to the new title.
+
 ### `<SystemMessage>`
 
 The conversation saying something about itself — not the reader, not the agent.

package/dist/Artifact/ChatLayout.d.ts

@@ -28,6 +28,19 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
      * it out and the sheet has neither, which is a sheet a thumb cannot dismiss.
      */
     onDismiss?: () => void;
+    /**
+     * Whether the conversation is a surface of its own.
+     *
+     * `"flush"` (the default): the conversation fills the layout and the pane is
+     * the only card — which is what a chat that owns the whole window wants.
+     *
+     * `"panes"`: two cards side by side on the page, with the same ring of space
+     * around both and the same gap between them. A divider would have said the
+     * same thing more cheaply and less truthfully: these are two surfaces, not
+     * one surface with a line through it. The pane the host draws itself goes
+     * beside a `"panes"` conversation and looks like it belongs there.
+     */
+    surface?: "flush" | "panes";
 }
 /**
  * Where the pane goes, decided once.
@@ -41,4 +54,4 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
  * What is left open is the part that actually differs — what is *in* the pane.
  * See `ArtifactPane`.
  */
-export declare function ChatLayout({ children, pane, onDismiss, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;
+export declare function ChatLayout({ children, pane, onDismiss, surface, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;

package/dist/ChatExperience/ChatExperience.d.ts

@@ -5,7 +5,7 @@ import { UseChatTurnsOptions, UseChatTurnsResult } from '../useChatTurns/useChat
 import { FoldMotion } from '../QuestionGroup/QuestionGroup';
 import { InlineAnimConfig } from '../ChatInput/ChatInput';
 import { TranscribeHandler } from '../voice/useVoiceInput';
-import { CustomPart, TurnPartUpdate } from '../turnParts/turnParts';
+import { CustomPart, CustomPartContext, TurnPartUpdate } from '../turnParts/turnParts';
 import { ComposerMenuItem } from '../ChatInput/AddCardsOverlay';
 import { ChatLabels } from '../labels/labels';
 import { Answer } from '../QuestionCard/types';
@@ -84,9 +84,7 @@ export interface ChatExperienceProps {
      * it stable — outside the component or in `useCallback` — or every row
      * re-renders on every frame of an answer arriving.
      */
-    renderPart?: (part: CustomPart, context: {
-        turnId: string;
-    }) => ReactNode;
+    renderPart?: (part: CustomPart, context: CustomPartContext) => ReactNode;
     /**
      * Every word the chat says, grouped by the component that says it. Partial:
      * anything left out stays English. Reaches every piece through context, so
@@ -127,6 +125,31 @@ export interface ChatExperienceProps {
     contextBase?: number;
     /** The pane beside the conversation, asked for the artifact that is open. */
     artifact?: (openId: string) => ChatExperienceArtifact | null;
+    /**
+     * Which artifact is open, held by the host. Left out (`undefined`), this
+     * component keeps it. `null` is "none open" — held, just empty.
+     */
+    openArtifactId?: string | null;
+    /** Somebody opened or closed one — a card pressed, the pane's X, a custom
+        card calling `openArtifact`. Called whether or not the state is held. */
+    onOpenArtifactChange?: (id: string | null) => void;
+    /**
+     * Who draws the pane. `"inline"` (the default): this component, beside the
+     * conversation, from `artifact`. `"none"`: nobody here — no pane, no room
+     * made for one. The cards still open and still show which one is open;
+     * the host draws the pane wherever its own layout wants it, usually with
+     * `openArtifactId` and `<ArtifactPane>`.
+     */
+    pane?: "inline" | "none";
+    /**
+     * Whether the conversation is a card of its own.
+     *
+     * `"flush"` (the default) fills the window, as before. `"panes"` makes it a
+     * surface on the page, so the pane beside it — the kit's or the host's own —
+     * is a second surface rather than a strip cut off the same one. See
+     * `ChatLayout`.
+     */
+    surface?: "flush" | "panes";
     /** The theme, if the host keeps it. Left off, this manages its own and puts
         a toggle in the header; `data-theme` on the root element either way, and
         unset until somebody chooses, so the kit follows the system preference —
@@ -154,4 +177,4 @@ export interface ChatExperienceProps {
     onDecideApproval?: (write: PartWriter, turnId: string, partId: string, decision: Decision) => void;
     className?: string;
 }
-export declare function ChatExperience({ onSend, chat: hostChat, renderPart, labels, headerActions: builtInActions, composerMenu, onTranscribe, onThreadReply, title: titleProp, backHref, backLabel, actions, placeholder, empty, contextTotal, contextBase, artifact, theme: themeProp, onThemeChange, cursor, selectionToggle, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;
+export declare function ChatExperience({ onSend, chat: hostChat, renderPart, labels, headerActions: builtInActions, composerMenu, onTranscribe, onThreadReply, title: titleProp, backHref, backLabel, actions, placeholder, empty, contextTotal, contextBase, artifact, openArtifactId: openArtifactProp, onOpenArtifactChange, pane: paneMode, surface, theme: themeProp, onThemeChange, cursor, selectionToggle, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;