@m6d/cortex-react 0.8.0 → 0.9.0

package/README.md

@@ -22,18 +22,27 @@ export function Chat() {
 }
 ```
 
-`CortexReactConfig` is the shared `CortexConfig` plus a React-only `toolComponents` slot (`Record<string, ComponentType<CortexToolComponentInputs>>`). Every other property, the client tools flow, and the media blocks are documented in [`packages/cortex-angular/README.md`](../cortex-angular/README.md); only the `toolComponents` and `injector` rows are Angular-specific.
+`CortexReactConfig` is the shared `CortexConfig` plus a React-only `toolComponents` field (`Record<string, ComponentType<CortexToolComponentInputs>>`). Every other property, the client tools flow, and the media blocks are documented in [`packages/cortex-angular/README.md`](../cortex-angular/README.md); only the `toolComponents` and `injector` rows are Angular-specific.
 
-## Custom header
+## Custom parts
 
-`renderHeader` replaces the header on both screens, the chat and the history,
-and receives the same context the Angular `cortexHeader` template does (fields
-listed in the Angular README):
+With `slots` you draw the widget's parts yourself: `header`, `landing` (the
+blank chat) and `threadList` (the history's list). Each is a component that
+takes the context the default is drawn from as its props, the same one
+Angular's `cortexSlot` templates get (fields listed in the Angular README). The
+landing's `composer` is a React node to place. Define slot components outside
+render: a new component each render remounts the part.
 
 ```tsx
-<CortexChatWidget
-  config={config}
-  renderHeader={(chat) => (
+import {
+  CortexChatWidget,
+  type CortexHeaderContext,
+  type CortexLandingContext,
+  type CortexReactSlots,
+} from '@m6d/cortex-react';
+
+function Header(chat: CortexHeaderContext) {
+  return (
     <div className="cortex-widget__chat-header">
       <div className="cortex-widget__chat-title-wrap">
         <p className="cortex-widget__chat-title">{chat.title ?? chat.agentName}</p>
@@ -42,8 +51,21 @@ listed in the Angular README):
         +
       </button>
     </div>
-  )}
-/>
+  );
+}
+
+function Landing(landing: CortexLandingContext) {
+  return (
+    <div className="cortex-widget__landing">
+      <h1>{landing.greeting}</h1>
+      {landing.composer}
+    </div>
+  );
+}
+
+const slots = { header: Header, landing: Landing } satisfies CortexReactSlots;
+
+<CortexChatWidget config={config} slots={slots} />;
 ```
 
 The theming tokens and the table actions are the same as Angular's.

package/dist/index.d.ts

@@ -19,6 +19,14 @@ export type ThreadSummary = {
 		name: string;
 	};
 };
+/**
+ * One landing-page chip: the widget shows `title` and sends `prompt` as the
+ * first message when clicked. The two may be the same text.
+ */
+export type Suggestion = {
+	title: string;
+	prompt: string;
+};
 export type CortexHeaders = Record<string, string>;
 /**
  * How the widget reaches its cortex server. `baseUrl` may be a thunk so a host
@@ -37,7 +45,9 @@ export type MediaRenderContext = {
  * Draws a closed media fence's `source` into `host`, resolves once drawn, and
  * returns the teardown. A consumer's `mediaRenderers` config entry has this
  * shape too: one per fence language, replacing the built-in of the same name
- * or adding a language of its own.
+ * or adding a language of its own. The same source can be drawn twice at once,
+ * inline and in its expanded view, so a renderer keeps no state that two
+ * drawings would share.
  */
 export type MediaRenderer = (host: HTMLElement, source: string, context: MediaRenderContext) => Promise<() => void>;
 export type MediaRenderers = Partial<Record<string, MediaRenderer>>;
@@ -45,31 +55,6 @@ export type MediaRenderers = Partial<Record<string, MediaRenderer>>;
 export type Localized<T> = T | Partial<Record<Locale, T>>;
 export type CortexViewMode = "helper" | "full";
 export type CortexTheme = "light" | "dark" | "system";
-/**
- * What a host's own header receives in place of the widget's: where the
- * widget is, what to show, and the actions the default header offers. One
- * header serves both screens; `screen` says which is showing.
- */
-export type CortexHeaderContext = {
-	screen: "chat" | "threads";
-	viewMode: CortexViewMode;
-	/** The open thread's title; null on a new chat. */
-	title: string | null;
-	/** `agentName` in the widget's locale. */
-	agentName: string | undefined;
-	isWorking: boolean;
-	/** Whether the host enabled the debug switch, and whether it is on. */
-	debug: {
-		shown: boolean;
-		on: boolean;
-	};
-	newChat: () => void;
-	/** Shows the history: the history screen, or in full mode the sidebar where it is hidden. */
-	openHistory: () => void;
-	/** Returns to the open chat from wherever `openHistory` went. */
-	closeHistory: () => void;
-	toggleDebug: () => void;
-};
 export type CortexToolCallContext = {
 	threadId: string;
 };
@@ -93,7 +78,7 @@ export type CortexToolComponentInputs = {
 };
 /**
  * The framework-neutral part of the widget's configuration. Each SDK extends it
- * with its own `toolComponents` slot, which is the one field whose type is
+ * with its own `toolComponents` field, which is the one field whose type is
  * inherently framework-bound.
  */
 export type CortexConfig = {
@@ -134,20 +119,95 @@ export type CortexConfig = {
 	trustSameOriginEmbeds?: boolean;
 	hooks?: CortexHooks;
 };
+/**
+ * What the header receives, the host's own or the widget's: where the widget
+ * is, what to show, and the actions the default header offers. One header
+ * serves both screens; `screen` says which is showing.
+ */
+export type CortexHeaderContext = {
+	screen: "chat" | "threads";
+	viewMode: CortexViewMode;
+	/** The open thread's title; null on a new chat. */
+	title: string | null;
+	/** `agentName` in the widget's locale. */
+	agentName: string | undefined;
+	/** How many conversations the history lists; 0 while it loads. */
+	threadCount: number;
+	isWorking: boolean;
+	/** Whether the host enabled the debug switch, and whether it is on. */
+	debug: {
+		shown: boolean;
+		on: boolean;
+	};
+	newChat: () => void;
+	/** Shows the history: the history screen, or in full mode the sidebar where it is hidden. */
+	openHistory: () => void;
+	/** Returns to the open chat from wherever `openHistory` went. */
+	closeHistory: () => void;
+	toggleDebug: () => void;
+};
+/**
+ * What the blank-chat landing receives, the host's own or the widget's. The
+ * composer arrives ready to place as the SDK's own view type (`View`), so a
+ * custom landing keeps the widget's attachments and send rules. Each SDK
+ * exports it as `CortexLandingContext` with its view type filled in.
+ */
+export type LandingContext<View> = {
+	/** The agent's greeting in the widget's locale, or the built-in one. */
+	greeting: string;
+	/** Empty until the handshake answers, and for an agent that takes no messages. */
+	suggestions: Suggestion[];
+	/** Newest first; undefined while the first load is out. */
+	threads: ThreadSummary[] | undefined;
+	/** The composer, or the notice an agent that takes no messages shows instead; empty until the handshake answers. */
+	composer: View;
+	/**
+	 * Sends a first message, which opens a thread and swaps the landing for it.
+	 * Does nothing until the handshake answers, or for an agent that takes no messages.
+	 */
+	send: (prompt: string) => void;
+	openThread: (thread: ThreadSummary) => void;
+};
+/** What the history's list receives, the host's own or the widget's. Its header is the header slot. */
+export type CortexThreadListContext = {
+	/** Newest first; undefined while the first load is out. */
+	threads: ThreadSummary[] | undefined;
+	/** The open thread's id; undefined on a new chat. */
+	selectedThreadId: string | undefined;
+	openThread: (thread: ThreadSummary) => void;
+	deleteThread: (threadId: string) => void;
+	newChat: () => void;
+};
+/** Each part of the widget a host can draw itself, with the context it receives. */
+export type CortexSlotContexts<View> = {
+	header: CortexHeaderContext;
+	landing: LandingContext<View>;
+	threadList: CortexThreadListContext;
+};
 export type CortexReactConfig = CortexConfig & {
 	toolComponents?: Record<string, ComponentType<CortexToolComponentInputs>>;
 };
-export type HeaderRenderer = (chat: CortexHeaderContext) => ReactNode;
+/** The landing's context, its composer a React node to place. */
+export type CortexLandingContext = LandingContext<ReactNode>;
+/**
+ * The parts of the widget a host draws itself: each a component taking the
+ * part's context as its props, the same type as the widget's default.
+ */
+export type CortexReactSlots = {
+	[Slot in keyof CortexSlotContexts<ReactNode>]?: ComponentType<CortexSlotContexts<ReactNode>[Slot]>;
+};
 /** The chat widget: the thread list, the open conversation and its composer, for the agent `config` points at. */
-export declare function CortexChatWidget({ config, className, renderHeader, }: {
+export declare function CortexChatWidget({ config, className, slots, }: {
 	config: CortexReactConfig;
 	/** Sizing classes for the host. */
 	className?: string;
 	/**
-	 * The host's own header. When given it replaces the default on both the
-	 * chat and the history screen, and receives the widget's state and actions.
+	 * The host's own parts. Each given one replaces the widget's default and
+	 * receives the context the default is drawn from as its props. `header`
+	 * serves both the chat and the history screen. Pass components defined
+	 * outside render: a new one each render remounts the part.
 	 */
-	renderHeader?: HeaderRenderer;
+	slots?: CortexReactSlots;
 }): import("react").JSX.Element;
 
 export {};