@humain/ui 2.1.62 → 2.1.65

package/dist/index236.js

@@ -1,50 +1,228 @@
-import { formatInteractionForLLM } from "./index235.js";
-import { useCallback, useMemo } from "react";
-//#region src/hooks/useInteractionHandler.ts
+import { assertNever } from "./index2.js";
+//#region src/lib/ai-interaction-format.ts
+var UNEXPECTED_COMPONENT_TYPE_MESSAGE = "Unexpected AI interaction component type";
 /**
-* Hook that creates a memoized interaction handler that automatically
-* formats interaction events for LLM consumption.
+* Normalize value to array
+*/
+function normalizeToArray(value) {
+	if (Array.isArray(value)) return value.map(String);
+	if (value === null || value === void 0) return [];
+	return [String(value)];
+}
+/**
+* Apply label mappings to values
+*/
+function applyLabels(values, labels) {
+	if (!labels) return values;
+	return values.map((v) => labels[v] || v);
+}
+/**
+* Format timestamp for display
+*/
+function formatTimestamp(timestamp) {
+	return new Date(timestamp).toISOString();
+}
+function formatSelectNatural(event, options) {
+	const values = normalizeToArray(event.value);
+	if (values.length === 0) return "I cleared my selection";
+	return `I selected: ${applyLabels(values, options?.labels).join(", ")}`;
+}
+function formatFormNatural(event) {
+	const data = event.value;
+	if (!data || Object.keys(data).length === 0) return `I submitted the ${event.componentId} form with no data`;
+	const fields = Object.entries(data).map(([key, value]) => `\u2022 ${key}: ${value}`).join("\n");
+	return `I submitted the ${event.componentId} form:\n${fields}`;
+}
+function formatTableNatural(event) {
+	const rows = event.value?.selectedRows || [];
+	if (rows.length === 0) return `I cleared row selection from ${event.componentId}`;
+	return `I selected rows ${rows.join(", ")} from ${event.componentId}`;
+}
+function formatChartNatural(event) {
+	const data = event.value;
+	if (!data?.label) return `I clicked on ${event.componentId}`;
+	return `I clicked on ${data.label} (value: ${data.value}) in ${event.componentId}`;
+}
+function formatComponentNatural(event) {
+	if (event.action === "submit" || event.action === "start") return `I answered ${event.componentId}: ${JSON.stringify(event.value)}`;
+	return `I ${event.action} ${event.componentId}: ${JSON.stringify(event.value)}`;
+}
+function formatNatural(event, options) {
+	let result;
+	switch (event.componentType) {
+		case "select":
+			result = formatSelectNatural(event, options);
+			break;
+		case "form":
+			result = formatFormNatural(event);
+			break;
+		case "table":
+			result = formatTableNatural(event);
+			break;
+		case "chart":
+			result = formatChartNatural(event);
+			break;
+		case "component":
+			result = formatComponentNatural(event);
+			break;
+		default: return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);
+	}
+	if (options?.includeTimestamp) result = `[${formatTimestamp(event.timestamp)}] ${result}`;
+	return result;
+}
+function formatSelectStructured(event, options) {
+	const result = {
+		type: "user_interaction",
+		component: "select",
+		id: event.componentId,
+		action: event.action,
+		selection: normalizeToArray(event.value)
+	};
+	if (options?.includeTimestamp) result.timestamp = event.timestamp;
+	return result;
+}
+function formatFormStructured(event, options) {
+	const result = {
+		type: "user_interaction",
+		component: "form",
+		id: event.componentId,
+		action: event.action,
+		data: event.value || {}
+	};
+	if (options?.includeTimestamp) result.timestamp = event.timestamp;
+	return result;
+}
+function formatTableStructured(event, options) {
+	const data = event.value;
+	const result = {
+		type: "user_interaction",
+		component: "table",
+		id: event.componentId,
+		action: event.action,
+		selectedRows: data?.selectedRows || []
+	};
+	if (options?.includeTimestamp) result.timestamp = event.timestamp;
+	return result;
+}
+function formatChartStructured(event, options) {
+	const data = event.value;
+	const result = {
+		type: "user_interaction",
+		component: "chart",
+		id: event.componentId,
+		action: event.action,
+		dataPoint: data
+	};
+	if (options?.includeTimestamp) result.timestamp = event.timestamp;
+	return result;
+}
+function formatComponentStructured(event, options) {
+	const result = {
+		type: "user_interaction",
+		component: "component",
+		id: event.componentId,
+		action: event.action,
+		value: event.value
+	};
+	if (options?.includeTimestamp) result.timestamp = event.timestamp;
+	return result;
+}
+function formatStructured(event, options) {
+	switch (event.componentType) {
+		case "select": return formatSelectStructured(event, options);
+		case "form": return formatFormStructured(event, options);
+		case "table": return formatTableStructured(event, options);
+		case "chart": return formatChartStructured(event, options);
+		case "component": return formatComponentStructured(event, options);
+		default: return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);
+	}
+}
+function formatSelectMarkdown(event, options) {
+	const values = normalizeToArray(event.value);
+	if (values.length === 0) return `**Selection (${event.componentId}):** _cleared_`;
+	const formatted = applyLabels(values, options?.labels).map((v) => `\`${v}\``).join(", ");
+	return `**Selection (${event.componentId}):** ${formatted}`;
+}
+function formatFormMarkdown(event) {
+	const data = event.value;
+	if (!data || Object.keys(data).length === 0) return `**Form Submission (${event.componentId}):** _empty_`;
+	const fields = Object.entries(data).map(([key, value]) => `- **${key}:** ${value}`).join("\n");
+	return `**Form Submission (${event.componentId}):**\n${fields}`;
+}
+function formatTableMarkdown(event) {
+	const rows = event.value?.selectedRows || [];
+	if (rows.length === 0) return `**Table Selection (${event.componentId}):** _none_`;
+	const formatted = rows.map((r) => `\`${r}\``).join(", ");
+	return `**Table Selection (${event.componentId}):** rows ${formatted}`;
+}
+function formatChartMarkdown(event) {
+	const data = event.value;
+	if (!data?.label) return `**Chart Click (${event.componentId}):** _no data_`;
+	return `**Chart Click (${event.componentId}):** ${data.label} (value: \`${data.value}\`)`;
+}
+function formatComponentMarkdown(event) {
+	return `**Component Interaction (${event.componentId}):** ${event.action} \`${JSON.stringify(event.value)}\``;
+}
+function formatMarkdown(event, options) {
+	let result;
+	switch (event.componentType) {
+		case "select":
+			result = formatSelectMarkdown(event, options);
+			break;
+		case "form":
+			result = formatFormMarkdown(event);
+			break;
+		case "table":
+			result = formatTableMarkdown(event);
+			break;
+		case "chart":
+			result = formatChartMarkdown(event);
+			break;
+		case "component":
+			result = formatComponentMarkdown(event);
+			break;
+		default: return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);
+	}
+	if (options?.includeTimestamp) result = `${result} _at ${formatTimestamp(event.timestamp)}_`;
+	return result;
+}
+/**
+* Format an AI interaction event for sending to an LLM.
+*
+* Supports three format modes:
+* - 'natural': Human-readable text (default)
+* - 'structured': JSON object structure
+* - 'markdown': Markdown formatted text
 *
-* @param options - Configuration options including the callback and format settings
-* @returns A stable callback function that handles interaction events
+* @param event - The interaction event to format
+* @param options - Formatting options
+* @returns Formatted string or object depending on format mode
 *
 * @example
-* ```tsx
-* function MyComponent() {
-*   const handleInteraction = useInteractionHandler({
-*     onInteraction: (event, formatted) => {
-*       console.log('Event:', event);
-*       console.log('Formatted:', formatted);
-*       // Send formatted message to LLM
-*     },
-*     format: 'natural', // or 'structured', 'markdown'
-*   });
+* ```ts
+* // Natural format (default)
+* formatInteractionForLLM(event)
+* // => "I selected: Fast delivery, Premium quality"
+*
+* // Structured format
+* formatInteractionForLLM(event, { format: 'structured' })
+* // => { type: 'user_interaction', component: 'select', ... }
 *
-*   return (
-*     <AIInteractionProvider onInteraction={handleInteraction}>
-*       <MarkdownRenderer>{markdownContent}</MarkdownRenderer>
-*     </AIInteractionProvider>
-*   );
-* }
+* // Markdown format
+* formatInteractionForLLM(event, { format: 'markdown' })
+* // => "**Selection (preferences):** `fast`, `quality`"
 * ```
 */
-function useInteractionHandler(options) {
-	const { onInteraction, format, includeTimestamp, labels } = options;
-	const formatOptions = useMemo(() => ({
-		format,
-		includeTimestamp,
-		labels
-	}), [
-		format,
-		includeTimestamp,
-		labels
-	]);
-	return useCallback((event) => {
-		const formatted = formatInteractionForLLM(event, formatOptions);
-		onInteraction(event, formatted);
-	}, [onInteraction, formatOptions]);
+function formatInteractionForLLM(event, options) {
+	const format = options?.format || "natural";
+	switch (format) {
+		case "structured": return formatStructured(event, options);
+		case "markdown": return formatMarkdown(event, options);
+		case "natural": return formatNatural(event, options);
+		default: return assertNever(format, "Unexpected AI interaction format");
+	}
 }
 //#endregion
-export { useInteractionHandler };
+export { formatInteractionForLLM };
 
 //# sourceMappingURL=index236.js.map

package/dist/index236.js.map

@@ -1 +1 @@
-{"version":3,"file":"index236.js","names":[],"sources":["../src/hooks/useInteractionHandler.ts"],"sourcesContent":["import { useCallback, useMemo } from 'react';\nimport type { AIInteractionEvent } from '@/components/organisms/ai/_shared/interaction-context';\nimport {\n  type FormatMode,\n  type FormatOptions,\n  formatInteractionForLLM,\n} from '@/lib/ai-interaction-format';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Options for the useInteractionHandler hook\n */\nexport interface UseInteractionHandlerOptions extends FormatOptions {\n  /**\n   * Callback invoked when an interaction occurs.\n   * Receives both the raw event and the formatted message.\n   */\n  onInteraction: (\n    event: AIInteractionEvent,\n    formattedMessage: string | object,\n  ) => void;\n}\n\n// =============================================================================\n// Hook\n// =============================================================================\n\n/**\n * Hook that creates a memoized interaction handler that automatically\n * formats interaction events for LLM consumption.\n *\n * @param options - Configuration options including the callback and format settings\n * @returns A stable callback function that handles interaction events\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const handleInteraction = useInteractionHandler({\n *     onInteraction: (event, formatted) => {\n *       console.log('Event:', event);\n *       console.log('Formatted:', formatted);\n *       // Send formatted message to LLM\n *     },\n *     format: 'natural', // or 'structured', 'markdown'\n *   });\n *\n *   return (\n *     <AIInteractionProvider onInteraction={handleInteraction}>\n *       <MarkdownRenderer>{markdownContent}</MarkdownRenderer>\n *     </AIInteractionProvider>\n *   );\n * }\n * ```\n */\nexport function useInteractionHandler(\n  options: UseInteractionHandlerOptions,\n): (event: AIInteractionEvent) => void {\n  const { onInteraction, format, includeTimestamp, labels } = options;\n\n  // Memoize format options to ensure stable reference\n  const formatOptions = useMemo<FormatOptions>(\n    () => ({\n      format,\n      includeTimestamp,\n      labels,\n    }),\n    [format, includeTimestamp, labels],\n  );\n\n  return useCallback(\n    (event: AIInteractionEvent) => {\n      const formatted = formatInteractionForLLM(event, formatOptions);\n      onInteraction(event, formatted);\n    },\n    [onInteraction, formatOptions],\n  );\n}\n\nexport type { FormatMode, FormatOptions };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,sBACd,SACqC;CACrC,MAAM,EAAE,eAAe,QAAQ,kBAAkB,WAAW;CAG5D,MAAM,gBAAgB,eACb;EACL;EACA;EACA;CACF,IACA;EAAC;EAAQ;EAAkB;CAAM,CACnC;CAEA,OAAO,aACJ,UAA8B;EAC7B,MAAM,YAAY,wBAAwB,OAAO,aAAa;EAC9D,cAAc,OAAO,SAAS;CAChC,GACA,CAAC,eAAe,aAAa,CAC/B;AACF"}
+{"version":3,"file":"index236.js","names":[],"sources":["../src/lib/ai-interaction-format.ts"],"sourcesContent":["import type { AIInteractionEvent } from '@/components/organisms/ai/_shared/interaction-context';\nimport { assertNever } from '@/lib/utils';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Format modes for LLM interaction formatting\n */\nexport type FormatMode = 'natural' | 'structured' | 'markdown';\n\n/**\n * Options for formatting interaction events\n */\nexport interface FormatOptions {\n  /** Output format mode. Defaults to 'natural' */\n  format?: FormatMode;\n  /** Whether to include timestamp in the output */\n  includeTimestamp?: boolean;\n  /** Label mappings for values (e.g., { 'fast': 'Fast delivery' }) */\n  labels?: Record<string, string>;\n}\n\ntype ChartInteractionValue = { label?: string; value?: number } | null;\n\nconst UNEXPECTED_COMPONENT_TYPE_MESSAGE =\n  'Unexpected AI interaction component type';\n\n// =============================================================================\n// Helper Functions\n// =============================================================================\n\n/**\n * Normalize value to array\n */\nfunction normalizeToArray(value: unknown): string[] {\n  if (Array.isArray(value)) {\n    return value.map(String);\n  }\n  if (value === null || value === undefined) {\n    return [];\n  }\n  return [String(value)];\n}\n\n/**\n * Apply label mappings to values\n */\nfunction applyLabels(\n  values: string[],\n  labels?: Record<string, string>,\n): string[] {\n  if (!labels) return values;\n  return values.map((v) => labels[v] || v);\n}\n\n/**\n * Format timestamp for display\n */\nfunction formatTimestamp(timestamp: number): string {\n  return new Date(timestamp).toISOString();\n}\n\n// =============================================================================\n// Natural Format\n// =============================================================================\n\nfunction formatSelectNatural(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): string {\n  const values = normalizeToArray(event.value);\n\n  if (values.length === 0) {\n    return 'I cleared my selection';\n  }\n\n  const labeledValues = applyLabels(values, options?.labels);\n  return `I selected: ${labeledValues.join(', ')}`;\n}\n\nfunction formatFormNatural(event: AIInteractionEvent): string {\n  const data = event.value as Record<string, unknown> | null;\n\n  if (!data || Object.keys(data).length === 0) {\n    return `I submitted the ${event.componentId} form with no data`;\n  }\n\n  const fields = Object.entries(data)\n    .map(([key, value]) => `\\u2022 ${key}: ${value}`)\n    .join('\\n');\n\n  return `I submitted the ${event.componentId} form:\\n${fields}`;\n}\n\nfunction formatTableNatural(event: AIInteractionEvent): string {\n  const data = event.value as { selectedRows?: string[] } | null;\n  const rows = data?.selectedRows || [];\n\n  if (rows.length === 0) {\n    return `I cleared row selection from ${event.componentId}`;\n  }\n\n  return `I selected rows ${rows.join(', ')} from ${event.componentId}`;\n}\n\nfunction formatChartNatural(event: AIInteractionEvent): string {\n  const data = event.value as ChartInteractionValue;\n\n  if (!data?.label) {\n    return `I clicked on ${event.componentId}`;\n  }\n\n  return `I clicked on ${data.label} (value: ${data.value}) in ${event.componentId}`;\n}\n\nfunction formatComponentNatural(event: AIInteractionEvent): string {\n  if (event.action === 'submit' || event.action === 'start') {\n    return `I answered ${event.componentId}: ${JSON.stringify(event.value)}`;\n  }\n\n  return `I ${event.action} ${event.componentId}: ${JSON.stringify(event.value)}`;\n}\n\nfunction formatNatural(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): string {\n  let result: string;\n\n  switch (event.componentType) {\n    case 'select':\n      result = formatSelectNatural(event, options);\n      break;\n    case 'form':\n      result = formatFormNatural(event);\n      break;\n    case 'table':\n      result = formatTableNatural(event);\n      break;\n    case 'chart':\n      result = formatChartNatural(event);\n      break;\n    case 'component':\n      result = formatComponentNatural(event);\n      break;\n    default:\n      return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);\n  }\n\n  if (options?.includeTimestamp) {\n    result = `[${formatTimestamp(event.timestamp)}] ${result}`;\n  }\n\n  return result;\n}\n\n// =============================================================================\n// Structured Format\n// =============================================================================\n\ninterface StructuredSelectResult {\n  type: 'user_interaction';\n  component: 'select';\n  id: string;\n  action: string;\n  selection: string[];\n  timestamp?: number;\n}\n\ninterface StructuredFormResult {\n  type: 'user_interaction';\n  component: 'form';\n  id: string;\n  action: string;\n  data: Record<string, unknown>;\n  timestamp?: number;\n}\n\ninterface StructuredTableResult {\n  type: 'user_interaction';\n  component: 'table';\n  id: string;\n  action: string;\n  selectedRows: string[];\n  timestamp?: number;\n}\n\ninterface StructuredChartResult {\n  type: 'user_interaction';\n  component: 'chart';\n  id: string;\n  action: string;\n  dataPoint: ChartInteractionValue;\n  timestamp?: number;\n}\n\ninterface StructuredComponentResult {\n  type: 'user_interaction';\n  component: 'component';\n  id: string;\n  action: string;\n  value: unknown;\n  timestamp?: number;\n}\n\ntype StructuredResult =\n  | StructuredSelectResult\n  | StructuredFormResult\n  | StructuredTableResult\n  | StructuredChartResult\n  | StructuredComponentResult;\n\nfunction formatSelectStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredSelectResult {\n  const result: StructuredSelectResult = {\n    type: 'user_interaction',\n    component: 'select',\n    id: event.componentId,\n    action: event.action,\n    selection: normalizeToArray(event.value),\n  };\n\n  if (options?.includeTimestamp) {\n    result.timestamp = event.timestamp;\n  }\n\n  return result;\n}\n\nfunction formatFormStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredFormResult {\n  const result: StructuredFormResult = {\n    type: 'user_interaction',\n    component: 'form',\n    id: event.componentId,\n    action: event.action,\n    data: (event.value as Record<string, unknown>) || {},\n  };\n\n  if (options?.includeTimestamp) {\n    result.timestamp = event.timestamp;\n  }\n\n  return result;\n}\n\nfunction formatTableStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredTableResult {\n  const data = event.value as { selectedRows?: string[] } | null;\n\n  const result: StructuredTableResult = {\n    type: 'user_interaction',\n    component: 'table',\n    id: event.componentId,\n    action: event.action,\n    selectedRows: data?.selectedRows || [],\n  };\n\n  if (options?.includeTimestamp) {\n    result.timestamp = event.timestamp;\n  }\n\n  return result;\n}\n\nfunction formatChartStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredChartResult {\n  const data = event.value as ChartInteractionValue;\n\n  const result: StructuredChartResult = {\n    type: 'user_interaction',\n    component: 'chart',\n    id: event.componentId,\n    action: event.action,\n    dataPoint: data,\n  };\n\n  if (options?.includeTimestamp) {\n    result.timestamp = event.timestamp;\n  }\n\n  return result;\n}\n\nfunction formatComponentStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredComponentResult {\n  const result: StructuredComponentResult = {\n    type: 'user_interaction',\n    component: 'component',\n    id: event.componentId,\n    action: event.action,\n    value: event.value,\n  };\n\n  if (options?.includeTimestamp) {\n    result.timestamp = event.timestamp;\n  }\n\n  return result;\n}\n\nfunction formatStructured(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): StructuredResult {\n  switch (event.componentType) {\n    case 'select':\n      return formatSelectStructured(event, options);\n    case 'form':\n      return formatFormStructured(event, options);\n    case 'table':\n      return formatTableStructured(event, options);\n    case 'chart':\n      return formatChartStructured(event, options);\n    case 'component':\n      return formatComponentStructured(event, options);\n    default:\n      return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);\n  }\n}\n\n// =============================================================================\n// Markdown Format\n// =============================================================================\n\nfunction formatSelectMarkdown(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): string {\n  const values = normalizeToArray(event.value);\n\n  if (values.length === 0) {\n    return `**Selection (${event.componentId}):** _cleared_`;\n  }\n\n  const labeledValues = applyLabels(values, options?.labels);\n  const formatted = labeledValues.map((v) => `\\`${v}\\``).join(', ');\n\n  return `**Selection (${event.componentId}):** ${formatted}`;\n}\n\nfunction formatFormMarkdown(event: AIInteractionEvent): string {\n  const data = event.value as Record<string, unknown> | null;\n\n  if (!data || Object.keys(data).length === 0) {\n    return `**Form Submission (${event.componentId}):** _empty_`;\n  }\n\n  const fields = Object.entries(data)\n    .map(([key, value]) => `- **${key}:** ${value}`)\n    .join('\\n');\n\n  return `**Form Submission (${event.componentId}):**\\n${fields}`;\n}\n\nfunction formatTableMarkdown(event: AIInteractionEvent): string {\n  const data = event.value as { selectedRows?: string[] } | null;\n  const rows = data?.selectedRows || [];\n\n  if (rows.length === 0) {\n    return `**Table Selection (${event.componentId}):** _none_`;\n  }\n\n  const formatted = rows.map((r) => `\\`${r}\\``).join(', ');\n  return `**Table Selection (${event.componentId}):** rows ${formatted}`;\n}\n\nfunction formatChartMarkdown(event: AIInteractionEvent): string {\n  const data = event.value as ChartInteractionValue;\n\n  if (!data?.label) {\n    return `**Chart Click (${event.componentId}):** _no data_`;\n  }\n\n  return `**Chart Click (${event.componentId}):** ${data.label} (value: \\`${data.value}\\`)`;\n}\n\nfunction formatComponentMarkdown(event: AIInteractionEvent): string {\n  return `**Component Interaction (${event.componentId}):** ${event.action} \\`${JSON.stringify(event.value)}\\``;\n}\n\nfunction formatMarkdown(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): string {\n  let result: string;\n\n  switch (event.componentType) {\n    case 'select':\n      result = formatSelectMarkdown(event, options);\n      break;\n    case 'form':\n      result = formatFormMarkdown(event);\n      break;\n    case 'table':\n      result = formatTableMarkdown(event);\n      break;\n    case 'chart':\n      result = formatChartMarkdown(event);\n      break;\n    case 'component':\n      result = formatComponentMarkdown(event);\n      break;\n    default:\n      return assertNever(event, UNEXPECTED_COMPONENT_TYPE_MESSAGE);\n  }\n\n  if (options?.includeTimestamp) {\n    result = `${result} _at ${formatTimestamp(event.timestamp)}_`;\n  }\n\n  return result;\n}\n\n// =============================================================================\n// Main Export\n// =============================================================================\n\n/**\n * Format an AI interaction event for sending to an LLM.\n *\n * Supports three format modes:\n * - 'natural': Human-readable text (default)\n * - 'structured': JSON object structure\n * - 'markdown': Markdown formatted text\n *\n * @param event - The interaction event to format\n * @param options - Formatting options\n * @returns Formatted string or object depending on format mode\n *\n * @example\n * ```ts\n * // Natural format (default)\n * formatInteractionForLLM(event)\n * // => \"I selected: Fast delivery, Premium quality\"\n *\n * // Structured format\n * formatInteractionForLLM(event, { format: 'structured' })\n * // => { type: 'user_interaction', component: 'select', ... }\n *\n * // Markdown format\n * formatInteractionForLLM(event, { format: 'markdown' })\n * // => \"**Selection (preferences):** `fast`, `quality`\"\n * ```\n */\nexport function formatInteractionForLLM(\n  event: AIInteractionEvent,\n  options?: FormatOptions,\n): string | object {\n  const format = options?.format || 'natural';\n\n  switch (format) {\n    case 'structured':\n      return formatStructured(event, options);\n    case 'markdown':\n      return formatMarkdown(event, options);\n    case 'natural':\n      return formatNatural(event, options);\n    default:\n      return assertNever(format, 'Unexpected AI interaction format');\n  }\n}\n"],"mappings":"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"}

package/dist/index237.js

@@ -0,0 +1,50 @@
+import { formatInteractionForLLM } from "./index236.js";
+import { useCallback, useMemo } from "react";
+//#region src/hooks/useInteractionHandler.ts
+/**
+* Hook that creates a memoized interaction handler that automatically
+* formats interaction events for LLM consumption.
+*
+* @param options - Configuration options including the callback and format settings
+* @returns A stable callback function that handles interaction events
+*
+* @example
+* ```tsx
+* function MyComponent() {
+*   const handleInteraction = useInteractionHandler({
+*     onInteraction: (event, formatted) => {
+*       console.log('Event:', event);
+*       console.log('Formatted:', formatted);
+*       // Send formatted message to LLM
+*     },
+*     format: 'natural', // or 'structured', 'markdown'
+*   });
+*
+*   return (
+*     <AIInteractionProvider onInteraction={handleInteraction}>
+*       <MarkdownRenderer>{markdownContent}</MarkdownRenderer>
+*     </AIInteractionProvider>
+*   );
+* }
+* ```
+*/
+function useInteractionHandler(options) {
+	const { onInteraction, format, includeTimestamp, labels } = options;
+	const formatOptions = useMemo(() => ({
+		format,
+		includeTimestamp,
+		labels
+	}), [
+		format,
+		includeTimestamp,
+		labels
+	]);
+	return useCallback((event) => {
+		const formatted = formatInteractionForLLM(event, formatOptions);
+		onInteraction(event, formatted);
+	}, [onInteraction, formatOptions]);
+}
+//#endregion
+export { useInteractionHandler };
+
+//# sourceMappingURL=index237.js.map

package/dist/index237.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index237.js","names":[],"sources":["../src/hooks/useInteractionHandler.ts"],"sourcesContent":["import { useCallback, useMemo } from 'react';\nimport type { AIInteractionEvent } from '@/components/organisms/ai/_shared/interaction-context';\nimport {\n  type FormatMode,\n  type FormatOptions,\n  formatInteractionForLLM,\n} from '@/lib/ai-interaction-format';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Options for the useInteractionHandler hook\n */\nexport interface UseInteractionHandlerOptions extends FormatOptions {\n  /**\n   * Callback invoked when an interaction occurs.\n   * Receives both the raw event and the formatted message.\n   */\n  onInteraction: (\n    event: AIInteractionEvent,\n    formattedMessage: string | object,\n  ) => void;\n}\n\n// =============================================================================\n// Hook\n// =============================================================================\n\n/**\n * Hook that creates a memoized interaction handler that automatically\n * formats interaction events for LLM consumption.\n *\n * @param options - Configuration options including the callback and format settings\n * @returns A stable callback function that handles interaction events\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const handleInteraction = useInteractionHandler({\n *     onInteraction: (event, formatted) => {\n *       console.log('Event:', event);\n *       console.log('Formatted:', formatted);\n *       // Send formatted message to LLM\n *     },\n *     format: 'natural', // or 'structured', 'markdown'\n *   });\n *\n *   return (\n *     <AIInteractionProvider onInteraction={handleInteraction}>\n *       <MarkdownRenderer>{markdownContent}</MarkdownRenderer>\n *     </AIInteractionProvider>\n *   );\n * }\n * ```\n */\nexport function useInteractionHandler(\n  options: UseInteractionHandlerOptions,\n): (event: AIInteractionEvent) => void {\n  const { onInteraction, format, includeTimestamp, labels } = options;\n\n  // Memoize format options to ensure stable reference\n  const formatOptions = useMemo<FormatOptions>(\n    () => ({\n      format,\n      includeTimestamp,\n      labels,\n    }),\n    [format, includeTimestamp, labels],\n  );\n\n  return useCallback(\n    (event: AIInteractionEvent) => {\n      const formatted = formatInteractionForLLM(event, formatOptions);\n      onInteraction(event, formatted);\n    },\n    [onInteraction, formatOptions],\n  );\n}\n\nexport type { FormatMode, FormatOptions };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,sBACd,SACqC;CACrC,MAAM,EAAE,eAAe,QAAQ,kBAAkB,WAAW;CAG5D,MAAM,gBAAgB,eACb;EACL;EACA;EACA;CACF,IACA;EAAC;EAAQ;EAAkB;CAAM,CACnC;CAEA,OAAO,aACJ,UAA8B;EAC7B,MAAM,YAAY,wBAAwB,OAAO,aAAa;EAC9D,cAAc,OAAO,SAAS;CAChC,GACA,CAAC,eAAe,aAAa,CAC/B;AACF"}