@kushagradhawan/kookie-blocks 0.1.9 → 0.1.11

package/src/components/markdown/StreamingMarkdown.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import React, { memo, useMemo, type ReactNode } from "react";
+import ReactMarkdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import rehypeRaw from "rehype-raw";
+import hardenReactMarkdown from "harden-react-markdown";
+import { Box, Flex } from "@kushagradhawan/kookie-ui";
+import { createMarkdownComponents } from "./createMarkdownComponents";
+import { completeUnterminatedMarkdown, parseMarkdownIntoBlocks } from "./utils/markdownStreaming";
+import type { MarkdownComponentOptions } from "./types";
+
+const HardenedMarkdown = hardenReactMarkdown(ReactMarkdown);
+
+const LINK_PREFIXES = ["https://", "http://", "/"];
+const IMAGE_PREFIXES = ["https://", "http://", "/", "data:"];
+const ALLOWED_PROTOCOLS = ["mailto:", "tel:", "data:", "http:", "https:"];
+const DEFAULT_APP_ORIGIN = typeof window !== "undefined" && window.location?.origin ? window.location.origin : "https://app.kookie.ai";
+
+/**
+ * Options for StreamingMarkdown component
+ */
+export type StreamingMarkdownOptions = MarkdownComponentOptions & {
+  /**
+   * Security origin for link/image validation
+   * @default window.location.origin or "https://app.kookie.ai"
+   */
+  defaultOrigin?: string;
+
+  /**
+   * Whether to enable block-level memoization for performance
+   * Recommended for streaming scenarios where content updates frequently
+   * @default true
+   */
+  enableBlockMemoization?: boolean;
+
+  /**
+   * Custom parser for splitting content into blocks
+   * If not provided, content will be rendered as a single block
+   * For optimal streaming performance, use marked.lexer with GFM enabled
+   */
+  blockParser?: (content: string) => Array<{ raw?: string }>;
+
+  /**
+   * Override default component mappings
+   */
+  components?: Partial<Components>;
+};
+
+type StreamingMarkdownProps = {
+  /**
+   * Markdown content to render (supports streaming/incomplete markdown)
+   */
+  content: string;
+
+  /**
+   * Unique identifier for this markdown instance (used for keys)
+   */
+  id: string;
+
+  /**
+   * Optional configuration
+   */
+  options?: StreamingMarkdownOptions;
+};
+
+type MarkdownBlockProps = {
+  content: string;
+  defaultOrigin: string;
+  components: Components;
+};
+
+/**
+ * Resolves the default origin for security validation
+ */
+function resolveDefaultOrigin(customOrigin?: string): string {
+  if (customOrigin) {
+    return customOrigin;
+  }
+  return DEFAULT_APP_ORIGIN;
+}
+
+/**
+ * Memoized markdown block component for efficient streaming rendering
+ */
+const MarkdownBlock = memo(
+  ({ content, defaultOrigin, components }: MarkdownBlockProps) => {
+    return (
+      <Box width="100%">
+        <HardenedMarkdown
+          defaultOrigin={defaultOrigin}
+          allowedLinkPrefixes={LINK_PREFIXES}
+          allowedImagePrefixes={IMAGE_PREFIXES}
+          allowedProtocols={ALLOWED_PROTOCOLS}
+          allowDataImages
+          components={components}
+          remarkPlugins={[remarkGfm]}
+          rehypePlugins={[rehypeRaw]}
+        >
+          {content}
+        </HardenedMarkdown>
+      </Box>
+    );
+  },
+  (previous, next) => previous.content === next.content && previous.defaultOrigin === next.defaultOrigin && previous.components === next.components
+);
+
+MarkdownBlock.displayName = "MarkdownBlock";
+
+/**
+ * StreamingMarkdown - A drop-in markdown renderer designed for AI streaming.
+ *
+ * Features:
+ * - Unterminated block parsing (handles incomplete markdown during streaming)
+ * - Block-level memoization for performance
+ * - Security hardening (validates links/images)
+ * - GitHub Flavored Markdown support
+ * - KookieUI component integration
+ * - Code syntax highlighting via CodeBlock
+ *
+ * @example
+ * ```tsx
+ * import { StreamingMarkdown } from '@kushagradhawan/kookie-blocks';
+ * import { marked } from 'marked';
+ *
+ * function ChatMessage({ message }) {
+ *   return (
+ *     <StreamingMarkdown
+ *       content={message.content}
+ *       id={message.id}
+ *       options={{
+ *         blockParser: (content) => marked.lexer(content, { gfm: true }),
+ *         enableBlockMemoization: true,
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function StreamingMarkdown({ content, id, options = {} }: StreamingMarkdownProps) {
+  const { defaultOrigin: customOrigin, enableBlockMemoization = true, blockParser, components: customComponents = {}, ...componentOptions } = options;
+
+  // Resolve security origin
+  const defaultOrigin = useMemo(() => resolveDefaultOrigin(customOrigin), [customOrigin]);
+
+  // Create component mappings with custom overrides
+  const markdownComponents = useMemo(() => {
+    const baseComponents = createMarkdownComponents(componentOptions);
+    return {
+      ...baseComponents,
+      ...customComponents,
+    };
+  }, [componentOptions, customComponents]);
+
+  // Parse content into blocks for memoization (if enabled and parser provided)
+  const blocks = useMemo(() => {
+    if (!enableBlockMemoization || !blockParser) {
+      // No block splitting - just complete unterminated markdown
+      const completed = completeUnterminatedMarkdown(content);
+      return completed.trim() ? [completed] : [];
+    }
+
+    return parseMarkdownIntoBlocks(content, blockParser);
+  }, [content, enableBlockMemoization, blockParser]);
+
+  if (!blocks.length) {
+    return null;
+  }
+
+  // Single block - no need for wrapper
+  if (blocks.length === 1) {
+    return <MarkdownBlock content={blocks[0]} defaultOrigin={defaultOrigin} components={markdownComponents} />;
+  }
+
+  // Multiple blocks - render with flex wrapper
+  return (
+    <Flex direction="column" gap="2" width="100%">
+      {blocks.map((block, index) => (
+        <MarkdownBlock key={`${id}-block-${index}`} content={block} defaultOrigin={defaultOrigin} components={markdownComponents} />
+      ))}
+    </Flex>
+  );
+}

package/src/components/markdown/createMarkdownComponents.tsx

@@ -0,0 +1,206 @@
+import React, { type ReactNode } from "react";
+import type { Components } from "react-markdown";
+import { Blockquote, Box, Code, Flex, Heading, Text, Table } from "@kushagradhawan/kookie-ui";
+import { CodeBlock } from "../code";
+import type { MarkdownComponentOptions, MarkdownChildrenProps } from "./types";
+
+/**
+ * Extracts language from className (e.g., "language-typescript" -> "typescript")
+ */
+function extractLanguage(className?: string): string {
+  if (!className) {
+    return "text";
+  }
+  const match = className.match(/language-([\w-]+)/i);
+  return match?.[1] ?? "text";
+}
+
+/**
+ * Extracts code string from ReactNode children
+ */
+function extractCode(children?: ReactNode): string {
+  let code = "";
+  if (!children) {
+    return code;
+  }
+  if (typeof children === "string") {
+    code = children;
+  } else if (Array.isArray(children)) {
+    code = children.map((child) => (typeof child === "string" ? child : "")).join("");
+  }
+  // Trim trailing newlines but preserve internal whitespace
+  return code.replace(/^\n+|\n+$/g, "");
+}
+
+/**
+ * Creates markdown component mappings that work with both react-markdown and MDX.
+ * Uses KookieUI components for consistent styling across all projects.
+ *
+ * @param options - Optional configuration for component behavior
+ * @returns Component mappings for markdown/MDX renderers
+ *
+ * @example
+ * ```tsx
+ * // In react-markdown
+ * <ReactMarkdown components={createMarkdownComponents()}>
+ *   {content}
+ * </ReactMarkdown>
+ *
+ * // In MDX
+ * export function useMDXComponents(components: MDXComponents) {
+ *   return {
+ *     ...createMarkdownComponents(),
+ *     ...components,
+ *   };
+ * }
+ * ```
+ */
+export function createMarkdownComponents(options: MarkdownComponentOptions = {}): Components {
+  const { codeBlockCollapsible = false, imageComponent, inlineCodeHighContrast = true } = options;
+
+  return {
+    // Headings with consistent visual hierarchy
+    h1: ({ children }: MarkdownChildrenProps) => (
+      <Heading size="8" weight="medium" as="h1" style={{ marginTop: "1rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+    h2: ({ children }: MarkdownChildrenProps) => (
+      <Heading weight="medium" size="5" as="h2" style={{ marginTop: "0.875rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+    h3: ({ children }: MarkdownChildrenProps) => (
+      <Heading weight="medium" size="4" as="h3" style={{ marginTop: "0.75rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+    h4: ({ children }: MarkdownChildrenProps) => (
+      <Heading weight="medium" size="3" as="h4" style={{ marginTop: "0.625rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+    h5: ({ children }: MarkdownChildrenProps) => (
+      <Heading weight="medium" size="3" as="h5" style={{ marginTop: "0.5rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+    h6: ({ children }: MarkdownChildrenProps) => (
+      <Heading weight="medium" size="3" as="h6" style={{ marginTop: "0.5rem", marginBottom: "0.5rem" }}>
+        {children}
+      </Heading>
+    ),
+
+    // Paragraph text
+    p: ({ children }: MarkdownChildrenProps) => (
+      <Text size="3" as="p" style={{ lineHeight: "1.6" }}>
+        {children}
+      </Text>
+    ),
+
+    // Code - inline vs block
+    code: ({ className, children, inline }: { className?: string; children?: ReactNode; inline?: boolean }) => {
+      const code = extractCode(children);
+
+      // Block code: has className (language) OR is not marked as inline
+      // Inline code: explicitly marked as inline=true, or no className and short single-line content
+      const isInlineCode = inline === true || (inline === undefined && !className && !code.includes("\n") && code.length < 100);
+
+      if (isInlineCode) {
+        return (
+          <Code highContrast={inlineCodeHighContrast} size="3">
+            {code}
+          </Code>
+        );
+      }
+
+      return (
+        <Box my="2" style={{ minWidth: 0 }}>
+          <CodeBlock code={code} language={extractLanguage(className)} collapsible={codeBlockCollapsible} />
+        </Box>
+      );
+    },
+
+    // Lists
+    ul: ({ children }: MarkdownChildrenProps) => (
+      <ul style={{ marginTop: "0.5rem", marginBottom: "0.5rem", lineHeight: "1.6", paddingLeft: "1.5rem", listStyleType: "disc" }}>{children}</ul>
+    ),
+    ol: ({ children }: MarkdownChildrenProps) => (
+      <ol style={{ marginTop: "0.5rem", marginBottom: "0.5rem", lineHeight: "1.6", paddingLeft: "1.5rem", listStyleType: "decimal" }}>{children}</ol>
+    ),
+    li: ({ children }: MarkdownChildrenProps) => <li style={{ marginBottom: "0.25rem", lineHeight: "1.6" }}>{children}</li>,
+
+    // Blockquote
+    blockquote: ({ children }: MarkdownChildrenProps) => <Blockquote>{children}</Blockquote>,
+
+    // Links
+    a: ({ href, children }: { href?: string; children?: ReactNode }) => (
+      <a href={href} style={{ color: "var(--accent-9)", textDecoration: "underline" }}>
+        {children}
+      </a>
+    ),
+
+    // Text styling
+    strong: ({ children }: MarkdownChildrenProps) => (
+      <Text weight="medium" style={{ lineHeight: "1.6" }}>
+        {children}
+      </Text>
+    ),
+    em: ({ children }: MarkdownChildrenProps) => <Text style={{ lineHeight: "1.6", fontStyle: "italic" }}>{children}</Text>,
+
+    // Horizontal rule
+    hr: () => (
+      <hr
+        style={{
+          color: "var(--gray-6)",
+          marginTop: "0.5rem",
+          marginBottom: "0.5rem",
+          height: "1px",
+          width: "100%",
+          opacity: 0.5,
+        }}
+      />
+    ),
+
+    // Pre wrapper (pass through to let code handle it)
+    pre: ({ children }: MarkdownChildrenProps) => <>{children}</>,
+
+    // Tables using KookieUI
+    table: ({ children }: MarkdownChildrenProps) => (
+      <Box my="2" style={{ overflowX: "auto" }}>
+        <Table.Root size="2" variant="ghost">
+          {children}
+        </Table.Root>
+      </Box>
+    ),
+    thead: ({ children }: MarkdownChildrenProps) => <Table.Header>{children}</Table.Header>,
+    tbody: ({ children }: MarkdownChildrenProps) => <Table.Body>{children}</Table.Body>,
+    tr: ({ children }: MarkdownChildrenProps) => <Table.Row>{children}</Table.Row>,
+    th: ({ children }: MarkdownChildrenProps) => <Table.ColumnHeaderCell>{children}</Table.ColumnHeaderCell>,
+    td: ({ children }: MarkdownChildrenProps) => <Table.Cell>{children}</Table.Cell>,
+
+    // HTML elements for raw HTML support
+    sub: ({ children }: MarkdownChildrenProps) => <sub>{children}</sub>,
+    sup: ({ children }: MarkdownChildrenProps) => <sup>{children}</sup>,
+    br: () => <br />,
+
+    // Images - use custom component if provided
+    img: imageComponent
+      ? (props: React.ImgHTMLAttributes<HTMLImageElement>) => {
+          const { src, alt, width, height } = props;
+          if (!src || typeof src !== "string") return null;
+          return imageComponent({
+            src,
+            alt: alt ?? "Image",
+            width: width ? String(width) : undefined,
+            height: height ? String(height) : undefined,
+          });
+        }
+      : undefined,
+
+    // Details/Summary for expandable sections
+    details: ({ children }: MarkdownChildrenProps) => <details style={{ padding: "0.5rem 0" }}>{children}</details>,
+    summary: ({ children }: MarkdownChildrenProps) => <summary style={{ cursor: "pointer", fontWeight: 500 }}>{children}</summary>,
+  };
+}
+

package/src/components/markdown/index.ts

@@ -0,0 +1,8 @@
+export { StreamingMarkdown } from "./StreamingMarkdown";
+export type { StreamingMarkdownOptions } from "./StreamingMarkdown";
+
+export { createMarkdownComponents } from "./createMarkdownComponents";
+export type { MarkdownComponentOptions, MarkdownChildrenProps } from "./types";
+
+export { completeUnterminatedMarkdown, parseMarkdownIntoBlocks } from "./utils/markdownStreaming";
+

package/src/components/markdown/types.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+
+/**
+ * Options for customizing markdown component behavior
+ */
+export type MarkdownComponentOptions = {
+  /**
+   * Whether code blocks should be collapsible
+   * @default false
+   */
+  codeBlockCollapsible?: boolean;
+
+  /**
+   * Custom image component
+   */
+  imageComponent?: (props: { src?: string; alt?: string; width?: string; height?: string }) => ReactNode;
+
+  /**
+   * Whether to use high contrast for inline code
+   * @default true
+   */
+  inlineCodeHighContrast?: boolean;
+};
+
+/**
+ * Common props for markdown child components
+ */
+export type MarkdownChildrenProps = {
+  children?: ReactNode;
+};
+