chatkit-bun 0.0.2

package/src/widgets/components.ts

@@ -0,0 +1,188 @@
+import type { ActionConfig } from "../actions";
+import type { DynamicWidgetComponent, DynamicWidgetRoot, WidgetJson } from "./types";
+
+type ActionConfigInput = {
+  type: ActionConfig["type"];
+  payload?: WidgetJson;
+  handler?: ActionConfig["handler"];
+  loadingBehavior?: ActionConfig["loadingBehavior"];
+  streaming?: ActionConfig["streaming"];
+  [key: string]: WidgetJson | undefined;
+};
+
+type WidgetPropValue =
+  | WidgetJson
+  | ActionConfigInput
+  | DynamicWidgetComponent
+  | DynamicWidgetComponent[]
+  | undefined;
+type WidgetProps = Record<string, WidgetPropValue>;
+
+function component<TType extends string, TProps extends WidgetProps>(
+  type: TType,
+  props: TProps,
+): { type: TType } & TProps {
+  return { ...props, type };
+}
+
+type Children = DynamicWidgetComponent[];
+type SingleChild = DynamicWidgetComponent;
+
+export type BasicProps = WidgetProps & { children?: Children };
+export function Basic(props: BasicProps = {}): DynamicWidgetRoot {
+  return component("Basic", props) as DynamicWidgetRoot;
+}
+
+export type CardProps = WidgetProps & {
+  children: Children;
+  asForm?: boolean;
+  confirm?: WidgetJson;
+  cancel?: WidgetJson;
+};
+export function Card(props: CardProps): DynamicWidgetRoot {
+  return component("Card", props) as DynamicWidgetRoot;
+}
+
+export type ListViewProps = WidgetProps & { children: DynamicWidgetComponent[] };
+export function ListView(props: ListViewProps): DynamicWidgetRoot {
+  return component("ListView", props) as DynamicWidgetRoot;
+}
+
+export type ListViewItemProps = WidgetProps & {
+  children: Children;
+  onClickAction?: ActionConfigInput;
+};
+export function ListViewItem(props: ListViewItemProps): DynamicWidgetComponent {
+  return component("ListViewItem", props);
+}
+
+export type TextProps = WidgetProps & { value: string; streaming?: boolean };
+export type TextWidget = { type: "Text" } & TextProps;
+export function Text(props: TextProps): TextWidget {
+  return component("Text", props);
+}
+
+export type MarkdownProps = WidgetProps & { value: string; streaming?: boolean };
+export type MarkdownWidget = { type: "Markdown" } & MarkdownProps;
+export function Markdown(props: MarkdownProps): MarkdownWidget {
+  return component("Markdown", props);
+}
+
+export type TitleProps = WidgetProps & { value: string };
+export function Title(props: TitleProps): DynamicWidgetComponent {
+  return component("Title", props);
+}
+
+export type CaptionProps = WidgetProps & { value: string };
+export function Caption(props: CaptionProps): DynamicWidgetComponent {
+  return component("Caption", props);
+}
+
+export type BadgeProps = WidgetProps & { label: string };
+export function Badge(props: BadgeProps): DynamicWidgetComponent {
+  return component("Badge", props);
+}
+
+export type BoxProps = WidgetProps & { children?: Children };
+export function Box(props: BoxProps = {}): DynamicWidgetComponent {
+  return component("Box", props);
+}
+
+export type RowProps = WidgetProps & { children?: Children };
+export function Row(props: RowProps = {}): DynamicWidgetComponent {
+  return component("Row", props);
+}
+
+export type ColProps = WidgetProps & { children?: Children };
+export function Col(props: ColProps = {}): DynamicWidgetComponent {
+  return component("Col", props);
+}
+
+export type FormProps = WidgetProps & {
+  children?: Children;
+  onSubmitAction?: ActionConfigInput;
+};
+export function Form(props: FormProps = {}): DynamicWidgetComponent {
+  return component("Form", props);
+}
+
+export function Divider(props: WidgetProps = {}): DynamicWidgetComponent {
+  return component("Divider", props);
+}
+
+export type IconProps = WidgetProps & { name: string };
+export function Icon(props: IconProps): DynamicWidgetComponent {
+  return component("Icon", props);
+}
+
+export type ImageProps = WidgetProps & { src: string; alt?: string };
+export function Image(props: ImageProps): DynamicWidgetComponent {
+  return component("Image", props);
+}
+
+export type ButtonProps = WidgetProps & {
+  label?: string;
+  onClickAction?: ActionConfigInput;
+};
+export function Button(props: ButtonProps = {}): DynamicWidgetComponent {
+  return component("Button", props);
+}
+
+export function Spacer(props: WidgetProps = {}): DynamicWidgetComponent {
+  return component("Spacer", props);
+}
+
+export type SelectProps = WidgetProps & { name: string; options: WidgetJson[] };
+export function Select(props: SelectProps): DynamicWidgetComponent {
+  return component("Select", props);
+}
+
+export type DatePickerProps = WidgetProps & { name: string };
+export function DatePicker(props: DatePickerProps): DynamicWidgetComponent {
+  return component("DatePicker", props);
+}
+
+export type CheckboxProps = WidgetProps & { name: string; label?: string };
+export function Checkbox(props: CheckboxProps): DynamicWidgetComponent {
+  return component("Checkbox", props);
+}
+
+export type InputProps = WidgetProps & { name: string };
+export function Input(props: InputProps): DynamicWidgetComponent {
+  return component("Input", props);
+}
+
+export type LabelProps = WidgetProps & { value: string; fieldName: string };
+export function Label(props: LabelProps): DynamicWidgetComponent {
+  return component("Label", props);
+}
+
+export type RadioGroupProps = WidgetProps & { name: string; options?: WidgetJson[] };
+export function RadioGroup(props: RadioGroupProps): DynamicWidgetComponent {
+  return component("RadioGroup", props);
+}
+
+export type TextareaProps = WidgetProps & { name: string };
+export function Textarea(props: TextareaProps): DynamicWidgetComponent {
+  return component("Textarea", props);
+}
+
+export type TransitionProps = WidgetProps & { children: SingleChild };
+export function Transition(props: TransitionProps): DynamicWidgetComponent {
+  return component("Transition", props);
+}
+
+export type ChartProps = WidgetProps & {
+  data: WidgetJson[];
+  series: WidgetJson[];
+  xAxis: string;
+  showYAxis?: boolean;
+  showLegend?: boolean;
+  showTooltip?: boolean;
+  barGap?: string | number;
+  barCategoryGap?: string | number;
+  flex?: string | number;
+};
+export function Chart(props: ChartProps): DynamicWidgetComponent {
+  return component("Chart", props);
+}

package/src/widgets/diff.ts

@@ -0,0 +1,151 @@
+import type { ThreadItemUpdate } from "../types/server";
+import { serializeWidget } from "./serialization";
+import type { WidgetRoot } from "./types";
+
+type WidgetNode = Record<string, unknown>;
+type WidgetDiffUpdate = Extract<
+  ThreadItemUpdate,
+  { type: "widget.root.updated" | "widget.streaming_text.value_delta" }
+>;
+
+function asNode(value: unknown): WidgetNode {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as WidgetNode)
+    : {};
+}
+
+function childrenOf(node: WidgetNode): WidgetNode[] {
+  const children = node.children;
+  if (Array.isArray(children)) return children.map(asNode);
+  if (children != null && typeof children === "object") return [asNode(children)];
+  return [];
+}
+
+function isStreamingText(node: WidgetNode): boolean {
+  return (node.type === "Text" || node.type === "Markdown") && typeof node.value === "string";
+}
+
+function jsonEqual(before: unknown, after: unknown): boolean {
+  return JSON.stringify(before) === JSON.stringify(after);
+}
+
+function isObjectRecord(value: unknown): value is WidgetNode {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function canValidateStreamingTextUpdate(before: WidgetNode, after: WidgetNode): boolean {
+  return (
+    isStreamingText(before) &&
+    isStreamingText(after) &&
+    typeof after.id === "string" &&
+    (before.id === after.id || before.id === undefined)
+  );
+}
+
+function valueRequiresFullReplace(before: unknown, after: unknown, isWidgetNode: boolean): boolean {
+  if (Array.isArray(before) && Array.isArray(after)) {
+    if (before.length !== after.length) return true;
+    for (let index = 0; index < before.length; index += 1) {
+      if (valueRequiresFullReplace(before[index], after[index], isWidgetNode)) return true;
+    }
+    return false;
+  }
+
+  if (isObjectRecord(before) && isObjectRecord(after)) {
+    return requiresFullReplace(before, after, isWidgetNode);
+  }
+
+  return !jsonEqual(before, after);
+}
+
+function requiresFullReplace(before: WidgetNode, after: WidgetNode, isWidgetNode: boolean): boolean {
+  if (before.type !== after.type || before.key !== after.key) {
+    return true;
+  }
+
+  const canValidateStreamingUpdate = isWidgetNode && canValidateStreamingTextUpdate(before, after);
+  if (before.id !== after.id && !canValidateStreamingUpdate) {
+    return true;
+  }
+
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of keys) {
+    const beforeValue = before[key];
+    const afterValue = after[key];
+
+    if (canValidateStreamingUpdate && (key === "id" || key === "value")) continue;
+    if (valueRequiresFullReplace(beforeValue, afterValue, isWidgetNode && key === "children")) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function streamingTextById(root: WidgetNode): Map<string, WidgetNode> {
+  const nodes = new Map<string, WidgetNode>();
+
+  function visit(node: WidgetNode): void {
+    if (isStreamingText(node) && typeof node.id === "string") {
+      nodes.set(node.id, node);
+    }
+    for (const child of childrenOf(node)) visit(child);
+  }
+
+  visit(root);
+  return nodes;
+}
+
+function validateStreamingTextUpdates(
+  beforeNodes: Map<string, WidgetNode>,
+  afterNodes: Map<string, WidgetNode>,
+): void {
+  for (const [id, afterNode] of afterNodes) {
+    const beforeNode = beforeNodes.get(id);
+    if (!beforeNode) {
+      throw new Error(
+        `Node ${id} was not present when the widget was initially rendered. All nodes with ID must persist across all widget updates.`,
+      );
+    }
+
+    const beforeValue = String(beforeNode.value);
+    const afterValue = String(afterNode.value);
+    if (!afterValue.startsWith(beforeValue)) {
+      throw new Error(
+        `Node ${id} was updated with a new value that is not a prefix of the initial value. All widget updates must be cumulative.`,
+      );
+    }
+  }
+}
+
+export function diffWidget(before: WidgetRoot, after: WidgetRoot): WidgetDiffUpdate[] {
+  const beforeRoot = serializeWidget(before);
+  const afterRoot = serializeWidget(after);
+  const beforeNodes = streamingTextById(beforeRoot);
+  const afterNodes = streamingTextById(afterRoot);
+
+  if (requiresFullReplace(beforeRoot, afterRoot, true)) {
+    return [{ type: "widget.root.updated", widget: afterRoot }];
+  }
+
+  validateStreamingTextUpdates(beforeNodes, afterNodes);
+
+  const updates: WidgetDiffUpdate[] = [];
+  for (const [id, afterNode] of afterNodes) {
+    const beforeNode = beforeNodes.get(id);
+    if (!beforeNode) continue;
+
+    const beforeValue = String(beforeNode.value);
+    const afterValue = String(afterNode.value);
+    if (beforeValue === afterValue) continue;
+
+    updates.push({
+      type: "widget.streaming_text.value_delta",
+      component_id: id,
+      delta: afterValue.slice(beforeValue.length),
+      done: afterNode.streaming !== true,
+    });
+  }
+
+  return updates;
+}

package/src/widgets/index.ts

@@ -0,0 +1,6 @@
+export * from "./components";
+export * from "./diff";
+export * from "./serialization";
+export * from "./stream";
+export * from "./template";
+export * from "./types";

package/src/widgets/serialization.ts

@@ -0,0 +1,46 @@
+import { DynamicWidgetRootSchema, type WidgetJson, type WidgetRoot } from "./types";
+
+function omitUndefinedDeep(value: unknown): WidgetJson {
+  if (Array.isArray(value)) {
+    return value
+      .filter((item) => item !== undefined)
+      .map((item) => omitUndefinedDeep(item)) as WidgetJson[];
+  }
+
+  if (value != null && typeof value === "object") {
+    const source =
+      typeof (value as { toJSON?: () => unknown }).toJSON === "function"
+        ? (value as { toJSON: () => unknown }).toJSON()
+        : value;
+
+    if (source == null || typeof source !== "object" || Array.isArray(source)) {
+      return omitUndefinedDeep(source);
+    }
+
+    const entries = Object.entries(source as Record<string, unknown>)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .map(([key, entryValue]) => [key, omitUndefinedDeep(entryValue)] as const);
+
+    return Object.fromEntries(entries) as WidgetJson;
+  }
+
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    value === null
+  ) {
+    return value;
+  }
+
+  throw new TypeError(`Unsupported widget value: ${String(value)}`);
+}
+
+export function serializeWidget(widget: WidgetRoot): Record<string, unknown> {
+  const parsed = DynamicWidgetRootSchema.parse(widget);
+  const serialized = omitUndefinedDeep(parsed);
+  if (serialized == null || typeof serialized !== "object" || Array.isArray(serialized)) {
+    throw new TypeError("Widget root must serialize to an object.");
+  }
+  return serialized as Record<string, unknown>;
+}

package/src/widgets/stream.ts

@@ -0,0 +1,104 @@
+import type { StoreItemType } from "../store";
+import { defaultGenerateId } from "../store";
+import type { ThreadItem, ThreadMetadata } from "../types/core";
+import type { ThreadStreamEvent } from "../types/server";
+import { diffWidget } from "./diff";
+import { serializeWidget } from "./serialization";
+import type { WidgetRoot } from "./types";
+
+export interface StreamWidgetOptions {
+  copyText?: string | null;
+  generateId?: (itemType: StoreItemType) => string;
+  now?: () => string;
+}
+
+type ResolvedStreamWidgetOptions = Required<Pick<StreamWidgetOptions, "generateId" | "now">> &
+  Pick<StreamWidgetOptions, "copyText">;
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<WidgetRoot> {
+  return (
+    value != null &&
+    typeof (value as Partial<AsyncIterable<WidgetRoot>>)[Symbol.asyncIterator] === "function"
+  );
+}
+
+function makeWidgetItem(
+  thread: ThreadMetadata,
+  itemId: string,
+  createdAt: string,
+  widget: WidgetRoot,
+  options: ResolvedStreamWidgetOptions,
+): ThreadItem {
+  return {
+    id: itemId,
+    type: "widget",
+    thread_id: thread.id,
+    created_at: createdAt,
+    widget: serializeWidget(widget),
+    copy_text: options.copyText ?? undefined,
+  };
+}
+
+export async function* streamWidget(
+  thread: ThreadMetadata,
+  widgetOrAsyncIterable: WidgetRoot | AsyncIterable<WidgetRoot>,
+  options: StreamWidgetOptions = {},
+): AsyncIterable<ThreadStreamEvent> {
+  const resolvedOptions: ResolvedStreamWidgetOptions = {
+    generateId: options.generateId ?? defaultGenerateId,
+    now: options.now ?? (() => new Date().toISOString()),
+    copyText: options.copyText,
+  };
+  const itemId = resolvedOptions.generateId("message");
+  const createdAt = resolvedOptions.now();
+
+  if (!isAsyncIterable(widgetOrAsyncIterable)) {
+    yield {
+      type: "thread.item.done",
+      item: makeWidgetItem(thread, itemId, createdAt, widgetOrAsyncIterable, resolvedOptions),
+    };
+    return;
+  }
+
+  const iterator = widgetOrAsyncIterable[Symbol.asyncIterator]();
+  let completed = false;
+  try {
+    const first = await iterator.next();
+    if (first.done) {
+      completed = true;
+      throw new Error("streamWidget async iterable must yield an initial widget.");
+    }
+
+    let lastState = first.value;
+    yield {
+      type: "thread.item.added",
+      item: makeWidgetItem(thread, itemId, createdAt, lastState, resolvedOptions),
+    };
+
+    for (;;) {
+      const next = await iterator.next();
+      if (next.done) {
+        completed = true;
+        break;
+      }
+
+      for (const update of diffWidget(lastState, next.value)) {
+        yield {
+          type: "thread.item.updated",
+          item_id: itemId,
+          update,
+        };
+      }
+      lastState = next.value;
+    }
+
+    yield {
+      type: "thread.item.done",
+      item: makeWidgetItem(thread, itemId, createdAt, lastState, resolvedOptions),
+    };
+  } finally {
+    if (!completed) {
+      await iterator.return?.();
+    }
+  }
+}

package/src/widgets/template.ts

@@ -0,0 +1,180 @@
+import { dirname, isAbsolute, join } from "node:path";
+
+import nunjucks from "nunjucks";
+
+import { serializeWidget } from "./serialization";
+import {
+  BasicRootSchema,
+  DynamicWidgetRootSchema,
+  type BasicRoot,
+  type DynamicWidgetRoot,
+} from "./types";
+
+const env = new nunjucks.Environment(undefined, {
+  autoescape: false,
+  throwOnUndefined: true,
+});
+
+env.addFilter("tojson", (value: unknown) => {
+  if (value === undefined) {
+    throw new Error("Missing template variable.");
+  }
+  return JSON.stringify(value);
+});
+
+export interface WidgetTemplateDefinition {
+  version: string;
+  name: string;
+  template: string;
+  dataSchema?: Record<string, unknown>;
+  jsonSchema?: Record<string, unknown>;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function callerDirectory(): string | null {
+  const stack = new Error().stack ?? "";
+  const lines = stack.split("\n").slice(2);
+
+  for (const line of lines) {
+    const match = line.match(/\(?((?:file:\/\/)?\/[^:)]+):\d+:\d+\)?/);
+    if (!match) continue;
+
+    const matchedPath = match[1];
+    if (matchedPath == null) continue;
+
+    const path = decodeURI(matchedPath.replace(/^file:\/\//, ""));
+    if (!path.includes("/src/widgets/template.")) {
+      return dirname(path);
+    }
+  }
+
+  return null;
+}
+
+function resolveWidgetPath(path: string): string {
+  if (isAbsolute(path)) {
+    return path;
+  }
+
+  const callerPath = callerDirectory();
+  if (callerPath != null) {
+    return join(callerPath, path);
+  }
+
+  return join(process.cwd(), path);
+}
+
+function normalizeData(data: unknown): Record<string, unknown> {
+  if (data == null) {
+    return {};
+  }
+
+  if (typeof data === "object" && typeof (data as { toJSON?: () => unknown }).toJSON === "function") {
+    const json = (data as { toJSON: () => unknown }).toJSON();
+    if (isPlainObject(json)) {
+      return json;
+    }
+    throw new TypeError("Widget template data toJSON() must return a plain object.");
+  }
+
+  if (isPlainObject(data)) {
+    return data;
+  }
+
+  throw new TypeError("Widget template data must be a plain object.");
+}
+
+function parseRenderedTemplate(rendered: string, name: string): unknown {
+  try {
+    return JSON.parse(rendered);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SyntaxError(`Rendered widget template "${name}" is not valid JSON: ${message}`);
+  }
+}
+
+function renderableTemplate(source: string): string {
+  let output = "";
+  let index = 0;
+
+  while (index < source.length) {
+    const expressionStart = source.indexOf("{{", index);
+    const blockStart = source.indexOf("{%", index);
+    const starts = [expressionStart, blockStart].filter((start) => start !== -1);
+    if (starts.length === 0) {
+      output += source.slice(index);
+      break;
+    }
+
+    const tagStart = Math.min(...starts);
+    const tagEndMarker = tagStart === expressionStart ? "}}" : "%}";
+    const tagEnd = source.indexOf(tagEndMarker, tagStart + 2);
+    if (tagEnd === -1) {
+      output += source.slice(index);
+      break;
+    }
+
+    const tagCloseEnd = tagEnd + tagEndMarker.length;
+    const tag = source
+      .slice(tagStart, tagCloseEnd)
+      .replace(/\b([A-Za-z_$][\w$]*)\[(\d+):\]/g, "$1.slice($2)");
+
+    output += source.slice(index, tagStart) + tag;
+    index = tagCloseEnd;
+  }
+
+  return output;
+}
+
+export class WidgetTemplate {
+  readonly version: string;
+  readonly name: string;
+  readonly template: string;
+  readonly dataSchema: Record<string, unknown>;
+  readonly jsonSchema?: Record<string, unknown>;
+
+  constructor(definition: WidgetTemplateDefinition) {
+    if (definition.version !== "1.0") {
+      throw new Error(`Unsupported widget spec version: ${definition.version}`);
+    }
+    if (typeof definition.name !== "string" || definition.name.length === 0) {
+      throw new TypeError("Widget template name is required.");
+    }
+    if (typeof definition.template !== "string" || definition.template.length === 0) {
+      throw new TypeError("Widget template source is required.");
+    }
+
+    this.version = definition.version;
+    this.name = definition.name;
+    this.template = definition.template;
+    this.jsonSchema = definition.jsonSchema;
+    this.dataSchema = definition.dataSchema ?? definition.jsonSchema ?? {};
+  }
+
+  static async fromFile(path: string): Promise<WidgetTemplate> {
+    const definition = await Bun.file(resolveWidgetPath(path)).json();
+    return new WidgetTemplate(definition as WidgetTemplateDefinition);
+  }
+
+  build(data?: unknown): DynamicWidgetRoot {
+    const rendered = env.renderString(renderableTemplate(this.template), normalizeData(data));
+    const parsed = parseRenderedTemplate(rendered, this.name);
+    const widget = DynamicWidgetRootSchema.parse(parsed);
+    return serializeWidget(widget) as DynamicWidgetRoot;
+  }
+
+  buildBasic(data?: unknown): BasicRoot {
+    const rendered = env.renderString(renderableTemplate(this.template), normalizeData(data));
+    const parsed = parseRenderedTemplate(rendered, this.name);
+    const widget = BasicRootSchema.parse(parsed);
+    return serializeWidget(widget) as BasicRoot;
+  }
+}