@kitn.ai/ui 0.16.0 → 0.18.0

package/frameworks/react/runtime.tsx

@@ -26,12 +26,35 @@ export interface WebComponentProps {
   children?: ReactNode;
 }
 
+// Per-element registration fires on the CLIENT, once per tag. The element modules
+// touch `window` at module-eval (Solid's runtime), so the thunk must never run on
+// the server — it is only ever called from a client effect, browser-gated here too.
+const registered = new Set<string>();
+function ensureRegistered(tagName: string, register?: () => Promise<unknown>): void {
+  if (!register || registered.has(tagName)) return;
+  if (typeof window === 'undefined' || typeof customElements === 'undefined') return;
+  registered.add(tagName);
+  if (customElements.get(tagName)) return; // already defined (e.g. via registerAll)
+  void register();
+}
+
+/** Eagerly register ALL kai-* elements (the register-all bundle). Opt-in escape
+ *  hatch for consumers who prefer no first-mount upgrade delay. Browser-only;
+ *  a no-op on the server. */
+export function registerAll(): Promise<unknown> | undefined {
+  if (typeof window === 'undefined' || typeof customElements === 'undefined') return undefined;
+  return import('@kitn.ai/ui/elements');
+}
+
 export function createWebComponent<P extends WebComponentProps>(
   tagName: string,
   /** DOM-property names to assign from props (incl. `theme`). */
   propNames: readonly string[],
-  /** Map of React handler prop → DOM event name, e.g. `{ onMessageAction: 'kai-message-action' }`. */
+  /** Map of React handler prop → DOM event name. */
   eventMap: Record<string, string>,
+  /** Client-only thunk that loads + registers this element (a literal dynamic
+   *  import of its `@kitn.ai/ui/elements/<name>` chunk). */
+  register?: () => Promise<unknown>,
 ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<HTMLElement>> {
   const eventEntries = Object.entries(eventMap);
 
@@ -71,6 +94,12 @@ export function createWebComponent<P extends WebComponentProps>(
       }
     });
 
+    // Client-only, deduped: load + register THIS element on first mount. The
+    // prop-assign effect's whenDefined guard re-applies props once it upgrades.
+    useLayoutEffect(() => {
+      ensureRegistered(tagName, register);
+    }, []);
+
     // Wire CustomEvent listeners ONCE per element. Each stable listener reads the
     // latest handler from handlersRef, so changing a handler's identity across
     // renders takes effect without add/remove churn, and listeners are removed on

package/frameworks/react/use-kai-chat.tsx

@@ -0,0 +1,87 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { Dispatch, SetStateAction } from 'react';
+import type { ChatMessage } from '../../src/elements/chat-types';
+export type { ChatMessage } from '../../src/elements/chat-types';
+import type { AttachmentData } from '../../src/components/attachment-types';
+import {
+  appendMessage, updateMessage, removeMessage, addSuggestion, removeSuggestion,
+  createAssistantStream, onStreamSettled, type AssistantStream, type SetMessages,
+} from '../../src/state';
+
+export interface UseKaiChatOptions {
+  /** Seed messages, read once at mount and copied. Later changes are ignored — drive updates through the returned ops. */
+  initialMessages?: ChatMessage[];
+  /** Seed suggestions, read once at mount and copied. Later changes are ignored. */
+  initialSuggestions?: string[];
+  onSubmit?: (detail: { value: string; attachments: AttachmentData[] }) => void | Promise<void>;
+}
+
+/** Owns chat state in React and exposes ergonomic, fully-typed controlled operations. */
+export interface KaiChatController {
+  messages: ChatMessage[];
+  setMessages: Dispatch<SetStateAction<ChatMessage[]>>;
+  suggestions: string[];
+  setSuggestions: Dispatch<SetStateAction<string[]>>;
+  loading: boolean;
+  append: (msg: ChatMessage) => void;
+  update: (id: string, patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage)) => void;
+  remove: (id: string) => void;
+  addSuggestion: (s: string) => void;
+  removeSuggestion: (s: string) => void;
+  clearSuggestions: () => void;
+  streamAssistant: (init?: Partial<ChatMessage>) => AssistantStream;
+  /** Spread onto `<Chat {...chat.bind} />` — wires messages, loading, suggestions, and kai-submit. */
+  bind: {
+    messages: ChatMessage[];
+    loading: boolean;
+    suggestions: string[];
+    onSubmit: (event: CustomEvent<{ value: string; attachments: AttachmentData[] }>) => void;
+  };
+}
+
+export function useKaiChat(options: UseKaiChatOptions = {}): KaiChatController {
+  // Copy the seed arrays so a caller mutating the array it passed in can't reach our state.
+  const [messages, setMessages] = useState<ChatMessage[]>(() => [...(options.initialMessages ?? [])]);
+  const [suggestions, setSuggestions] = useState<string[]>(() => [...(options.initialSuggestions ?? [])]);
+  const [loading, setLoading] = useState(false);
+
+  // Keep onSubmit current without re-binding the listener identity.
+  const onSubmitRef = useRef(options.onSubmit);
+  onSubmitRef.current = options.onSubmit;
+
+  const set: SetMessages = useCallback((updater) => setMessages(updater), []);
+
+  const append = useCallback((msg: ChatMessage) => set((prev) => appendMessage(prev, msg)), [set]);
+  const update = useCallback(
+    (id: string, patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage)) =>
+      set((prev) => updateMessage(prev, id, patch)),
+    [set],
+  );
+  const remove = useCallback((id: string) => set((prev) => removeMessage(prev, id)), [set]);
+  const addSug = useCallback((s: string) => setSuggestions((prev) => addSuggestion(prev, s)), []);
+  const removeSug = useCallback((s: string) => setSuggestions((prev) => removeSuggestion(prev, s)), []);
+  const clearSuggestions = useCallback(() => setSuggestions([]), []);
+
+  const streamAssistant = useCallback((init?: Partial<ChatMessage>): AssistantStream => {
+    setLoading(true);
+    return onStreamSettled(createAssistantStream(set, init), () => setLoading(false));
+  }, [set]);
+
+  const onSubmit = useCallback(
+    (event: CustomEvent<{ value: string; attachments: AttachmentData[] }>) => {
+      void onSubmitRef.current?.(event.detail);
+    },
+    [],
+  );
+
+  const bind = useMemo(
+    () => ({ messages, loading, suggestions, onSubmit }),
+    [messages, loading, suggestions, onSubmit],
+  );
+
+  return {
+    messages, setMessages, suggestions, setSuggestions, loading,
+    append, update, remove, addSuggestion: addSug, removeSuggestion: removeSug, clearSuggestions,
+    streamAssistant, bind,
+  };
+}