@kushagradhawan/kookie-blocks 0.1.6 → 0.1.8

package/src/components/code/LanguageBadge.tsx

@@ -1,28 +1,76 @@
 import React from "react";
 import { Code } from "@kushagradhawan/kookie-ui";
 
-interface LanguageBadgeProps {
-  language: string;
-}
+const LANGUAGE_DISPLAY_MAP: Record<string, string> = {
+  js: "JS",
+  javascript: "JS",
+  jsx: "JSX",
+  ts: "TS",
+  typescript: "TS",
+  tsx: "TSX",
+  py: "Python",
+  python: "Python",
+  rb: "Ruby",
+  ruby: "Ruby",
+  sh: "Shell",
+  bash: "Shell",
+  shell: "Shell",
+  zsh: "Shell",
+  css: "CSS",
+  scss: "SCSS",
+  sass: "Sass",
+  less: "Less",
+  html: "HTML",
+  xml: "XML",
+  json: "JSON",
+  yaml: "YAML",
+  yml: "YAML",
+  md: "Markdown",
+  markdown: "Markdown",
+  mdx: "MDX",
+  sql: "SQL",
+  graphql: "GraphQL",
+  gql: "GraphQL",
+  go: "Go",
+  rust: "Rust",
+  rs: "Rust",
+  swift: "Swift",
+  kotlin: "Kotlin",
+  java: "Java",
+  cpp: "C++",
+  c: "C",
+  cs: "C#",
+  csharp: "C#",
+  php: "PHP",
+  vue: "Vue",
+  svelte: "Svelte",
+  astro: "Astro",
+  dockerfile: "Docker",
+  docker: "Docker",
+  text: "Text",
+  plaintext: "Text",
+  txt: "Text",
+};
 
-function formatLanguage(lang: string): string {
-  const languageMap: Record<string, string> = {
-    js: "JS",
-    jsx: "JSX",
-    ts: "TS",
-    tsx: "TSX",
-    py: "Python",
-    rb: "Ruby",
-    sh: "Shell",
-    bash: "Bash",
-    text: "plaintext",
-  };
+/**
+ * Formats a language identifier for display in the badge.
+ * Converts technical identifiers to human-readable labels.
+ */
+export function formatLanguageForDisplay(lang: string): string {
+  const normalized = lang.toLowerCase().trim();
+  return LANGUAGE_DISPLAY_MAP[normalized] || lang.toUpperCase();
+}
 
-  return languageMap[lang.toLowerCase()] || lang;
+interface LanguageBadgeProps {
+  language: string;
 }
 
+/**
+ * Displays the programming language as a small badge.
+ * Uses Kookie UI's Code component with consistent styling.
+ */
 export function LanguageBadge({ language }: LanguageBadgeProps) {
-  const displayLanguage = formatLanguage(language);
+  const displayLanguage = formatLanguageForDisplay(language);
 
   return (
     <Code size="1" color="gray" highContrast>
@@ -30,4 +78,3 @@ export function LanguageBadge({ language }: LanguageBadgeProps) {
     </Code>
   );
 }
-

package/src/components/code/index.ts

@@ -1,3 +1,6 @@
-// Public API - only CodeBlock is exported
-export { CodeBlock } from "./CodeBlock";
-export type { CodeBlockProps } from "./types";
+// Public API
+export { CodeBlock, useCodeBlockContext } from "./CodeBlock";
+export { useCodeCard } from "./useCodeCard";
+export { LanguageBadge, formatLanguageForDisplay } from "./LanguageBadge";
+export type { CodeBlockProps, ShikiConfig, PreviewBackgroundProps } from "./types";
+export { extractTextFromChildren, extractLanguageFromChildren, isReactElement } from "./types";

package/src/components/code/types.ts

@@ -1,32 +1,224 @@
-import type { ReactNode } from "react";
+import type { ReactNode, ReactElement } from "react";
 
-export interface CodeBlockProps {
-  // Content modes (mutually exclusive)
-  children?: ReactNode; // Pre-highlighted HTML from build-time (MDX)
-  code?: string; // Raw code to highlight at runtime
-  language?: string; // Language for runtime highlighting
-
-  // Optional features
-  preview?: ReactNode; // Preview component (for docs)
-  showCopy?: boolean; // Default: true
-  showLanguage?: boolean; // Default: true
-  file?: string; // File path label
-  collapsible?: boolean; // Enable expand/collapse
-  collapsedHeight?: number; // Default: 360px
-
-  // Preview styling (for kookie-ui docs)
-  background?: "none" | "dots" | string; // Background type
-  backgroundProps?: {
-    dotSize?: number;
-    color?: string;
-    backgroundColor?: string;
-    height?: string;
-    width?: string;
-    radius?: string;
+/**
+ * Shiki syntax highlighting configuration.
+ * Controls themes and advanced highlighting options.
+ */
+export interface ShikiConfig {
+  /**
+   * Theme names for light and dark modes.
+   * Uses Shiki's dual-theme mode for automatic theme switching.
+   * @default { light: 'one-light', dark: 'one-dark-pro' }
+   */
+  themes?: {
+    light?: string;
+    dark?: string;
   };
 
-  // Theme
-  lightTheme?: string; // Default: 'one-light'
-  darkTheme?: string; // Default: 'one-dark-pro'
+  /**
+   * Language aliases for custom language mapping.
+   * @example { js: 'javascript', ts: 'typescript' }
+   */
+  langAlias?: Record<string, string>;
+
+  /**
+   * Shiki transformers for custom code transformations.
+   * Useful for line highlighting, diff syntax, etc.
+   * @see https://shiki.style/guide/transformers
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  transformers?: any[];
+
+  /**
+   * Metadata string passed to transformers.
+   * Often used for line highlighting syntax like `{1,3-5}`.
+   */
+  meta?: string;
+}
+
+/**
+ * Background configuration for preview section.
+ */
+export interface PreviewBackgroundProps {
+  /** Dot size in pixels (for dots background) */
+  dotSize?: number;
+  /** Dot color (CSS value) */
+  color?: string;
+  /** Background color (CSS value) */
+  backgroundColor?: string;
+  /** Preview section height */
+  height?: string;
+  /** Preview section width */
+  width?: string;
+  /** Border radius token (e.g., "3" for var(--radius-3)) */
+  radius?: string;
 }
 
+/**
+ * CodeBlock Component Props
+ *
+ * A unified code block component supporting:
+ * - Runtime syntax highlighting via Shiki (`code` + `language`)
+ * - Build-time highlighted content from MDX/rehype-pretty-code (`children`)
+ * - Optional preview section for documentation
+ */
+export interface CodeBlockProps {
+  /**
+   * Raw code string for runtime Shiki highlighting.
+   * Mutually exclusive with `children`.
+   */
+  code?: string;
+
+  /**
+   * Language identifier for syntax highlighting.
+   * Required when using `code` prop.
+   * @example "typescript", "tsx", "python", "bash"
+   */
+  language?: string;
+
+  /**
+   * Pre-highlighted content from MDX/rehype-pretty-code.
+   * Mutually exclusive with `code` prop.
+   * Language is auto-detected from `data-language` or `className="language-xxx"`.
+   */
+  children?: ReactNode;
+
+  /**
+   * Shiki syntax highlighting configuration.
+   * Only applies when using `code` prop (runtime highlighting).
+   */
+  shikiConfig?: ShikiConfig;
+
+  /**
+   * Show copy-to-clipboard button.
+   * @default true
+   */
+  showCopy?: boolean;
+
+  /**
+   * Show language badge.
+   * @default true
+   */
+  showLanguage?: boolean;
+
+  /**
+   * Show line numbers.
+   * @default true
+   */
+  showLineNumbers?: boolean;
+
+  /**
+   * File path displayed above the code block.
+   * @example "src/components/Button.tsx"
+   */
+  file?: string;
+
+  /**
+   * Enable expand/collapse for long code blocks.
+   * @default true
+   */
+  collapsible?: boolean;
+
+  /**
+   * Height threshold (in pixels) before code is collapsed.
+   * @default 360
+   */
+  collapsedHeight?: number;
+
+  /**
+   * Preview component displayed above the code block.
+   * Useful for showcasing component examples in documentation.
+   */
+  preview?: ReactNode;
+
+  /**
+   * Background style for preview section.
+   * - `"none"`: Plain card background
+   * - `"dots"`: Dotted pattern background
+   * - `string`: Image URL for custom background
+   * @default "none"
+   */
+  background?: "none" | "dots" | string;
+
+  /**
+   * Customization for preview background.
+   */
+  backgroundProps?: PreviewBackgroundProps;
+}
+
+/**
+ * Type guard for React elements with props.
+ */
+export function isReactElement(node: unknown): node is ReactElement {
+  return typeof node === "object" && node !== null && "props" in node && typeof (node as ReactElement).props === "object";
+}
+
+/**
+ * Extracts plain text content from React children.
+ * Used to get copyable code from pre-highlighted MDX content.
+ */
+export function extractTextFromChildren(children: ReactNode): string {
+  if (typeof children === "string") return children;
+  if (typeof children === "number") return String(children);
+  if (!children) return "";
+
+  if (Array.isArray(children)) {
+    return children.map(extractTextFromChildren).join("");
+  }
+
+  if (isReactElement(children)) {
+    const props = children.props as { children?: ReactNode };
+    if (props.children) {
+      return extractTextFromChildren(props.children);
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Extracts language identifier from pre-highlighted MDX children.
+ * Checks `data-language` attribute and `className="language-xxx"` pattern.
+ */
+export function extractLanguageFromChildren(children: ReactNode): string {
+  const findLanguage = (node: ReactNode): string | null => {
+    if (!node) return null;
+
+    if (isReactElement(node)) {
+      const props = node.props as {
+        "data-language"?: string;
+        className?: string;
+        class?: string;
+        children?: ReactNode;
+      };
+
+      // Check data-language attribute (rehype-pretty-code)
+      if (props["data-language"]) {
+        return props["data-language"];
+      }
+
+      // Check className for language-xxx pattern
+      const className = props.className || props.class || "";
+      if (typeof className === "string") {
+        const match = className.match(/language-([\w-]+)/i);
+        if (match) return match[1];
+      }
+
+      // Recursively check children
+      if (props.children) {
+        if (Array.isArray(props.children)) {
+          for (const child of props.children) {
+            const lang = findLanguage(child);
+            if (lang) return lang;
+          }
+        } else {
+          return findLanguage(props.children);
+        }
+      }
+    }
+
+    return null;
+  };
+
+  return findLanguage(children) || "text";
+}

package/src/components/code/useCodeCard.ts

@@ -0,0 +1,82 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+
+const COPY_FEEDBACK_DURATION_MS = 2000;
+
+interface UseCodeCardOptions {
+  code: string;
+  collapsedHeight: number;
+}
+
+interface UseCodeCardReturn {
+  isExpanded: boolean;
+  shouldShowToggle: boolean;
+  copied: boolean;
+  contentRef: React.RefObject<HTMLDivElement | null>;
+  contentMaxHeight: number;
+  handleToggle: () => void;
+  handleCopy: () => Promise<void>;
+}
+
+/**
+ * Shared hook for code card UI behavior.
+ * Handles expand/collapse state and copy functionality.
+ */
+export function useCodeCard({ code, collapsedHeight }: UseCodeCardOptions): UseCodeCardReturn {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [contentHeight, setContentHeight] = useState(collapsedHeight);
+  const [copied, setCopied] = useState(false);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const resetTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const shouldShowToggle = contentHeight > collapsedHeight;
+  const contentMaxHeight = isExpanded ? contentHeight : collapsedHeight;
+
+  // Measure content height on mount and when content changes
+  useEffect(() => {
+    if (contentRef.current) {
+      setContentHeight(contentRef.current.scrollHeight);
+    }
+  });
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (resetTimeoutRef.current) {
+        clearTimeout(resetTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  const handleToggle = useCallback(() => {
+    setIsExpanded((prev) => !prev);
+  }, []);
+
+  const handleCopy = useCallback(async () => {
+    if (!code.trim()) return;
+
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+
+      if (resetTimeoutRef.current) {
+        clearTimeout(resetTimeoutRef.current);
+      }
+      resetTimeoutRef.current = setTimeout(() => setCopied(false), COPY_FEEDBACK_DURATION_MS);
+    } catch (error) {
+      // Log error in development, fail gracefully in production
+      if (process.env.NODE_ENV === "development") {
+        console.error("[CodeBlock] Failed to copy to clipboard:", error);
+      }
+    }
+  }, [code]);
+
+  return {
+    isExpanded,
+    shouldShowToggle,
+    copied,
+    contentRef,
+    contentMaxHeight,
+    handleToggle,
+    handleCopy,
+  };
+}

package/src/components/index.css

@@ -16,68 +16,41 @@
   position: relative;
 }
 
-/* Code block content (the pre part, below the header) */
-.code-block-content {
-  width: 100%;
-  min-width: 0;
-  overflow-x: auto;
-  /* Hide scrollbars while keeping scroll functionality */
-  scrollbar-width: none; /* Firefox */
-  -ms-overflow-style: none; /* IE/Edge */
-}
-
-/* Hide scrollbars for webkit browsers */
-.code-block-content::-webkit-scrollbar,
-.code-block-content::-webkit-scrollbar-horizontal,
-.code-block-content::-webkit-scrollbar-vertical,
-.code-block-content::-webkit-scrollbar-track,
-.code-block-content::-webkit-scrollbar-thumb,
-.code-block-content::-webkit-scrollbar-corner {
-  display: none !important;
-  width: 0 !important;
-  height: 0 !important;
-}
-
-/* Also hide scrollbars on any pre/code elements inside code content */
-.code-block-content pre::-webkit-scrollbar,
-.code-block-content pre::-webkit-scrollbar-horizontal,
-.code-block-content pre::-webkit-scrollbar-vertical,
-.code-block-content pre::-webkit-scrollbar-track,
-.code-block-content pre::-webkit-scrollbar-thumb,
-.code-block-content pre::-webkit-scrollbar-corner,
-.code-block-content code::-webkit-scrollbar,
-.code-block-content code::-webkit-scrollbar-horizontal,
-.code-block-content code::-webkit-scrollbar-vertical,
-.code-block-content code::-webkit-scrollbar-track,
-.code-block-content code::-webkit-scrollbar-thumb,
-.code-block-content code::-webkit-scrollbar-corner {
-  display: none !important;
-  width: 0 !important;
-  height: 0 !important;
-}
-
 /* Pre elements inside code content */
-.code-content pre,
-.code-block-content pre {
-  overflow-x: visible;
-  max-width: 100%;
-  min-width: 0;
+.code-content pre {
   margin: 0;
   width: 100%;
   box-sizing: border-box;
-  scrollbar-width: none;
-  -ms-overflow-style: none;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-2);
+  line-height: 1.75;
+  padding: var(--space-3);
+  overflow-x: auto;
+}
+
+/* Rehype-pretty-code theme support */
+pre[data-theme] code {
+  background: none !important;
 }
 
-/* Ensure Shiki-generated pre elements fill width */
-.code-block-content > pre {
-  width: 100% !important;
-  min-width: 0;
+pre[data-theme] code span {
+  color: var(--shiki-light);
+  font-style: var(--shiki-light-font-style);
+  font-weight: var(--shiki-light-font-weight);
+  text-decoration: var(--shiki-light-text-decoration);
+}
+
+.dark pre[data-theme] code span,
+.dark-theme pre[data-theme] code span,
+[data-appearance="dark"] pre[data-theme] code span {
+  color: var(--shiki-dark) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
 }
 
 /* Code elements inside pre */
-.code-content pre code,
-.code-block-content pre code {
+.code-content pre code {
   font-family: var(--font-mono);
   font-size: var(--font-size-2);
   line-height: 1.75;
@@ -89,16 +62,14 @@
 }
 
 /* Shiki line spans */
-.code-content pre code .line,
-.code-block-content pre code .line {
+.code-content pre code .line {
   display: flex;
   align-items: center;
   gap: 0;
 }
 
-/* Line numbers */
-.code-content pre code .line::before,
-.code-block-content pre code .line::before {
+/* Line numbers (shown by default) */
+.code-content pre code .line::before {
   counter-increment: line;
   content: counter(line);
   display: inline-block;
@@ -111,6 +82,41 @@
   margin-right: var(--space-4);
 }
 
+/* Hide line numbers when disabled */
+.code-content.hide-line-numbers pre code .line::before {
+  display: none;
+}
+
+/* Loading skeleton */
+.code-skeleton {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.code-skeleton-line {
+  height: 1em;
+  background: linear-gradient(
+    90deg,
+    var(--gray-a3) 0%,
+    var(--gray-a4) 50%,
+    var(--gray-a3) 100%
+  );
+  background-size: 200% 100%;
+  animation: code-skeleton-shimmer 1.5s ease-in-out infinite;
+  border-radius: var(--radius-1);
+}
+
+@keyframes code-skeleton-shimmer {
+  0% {
+    background-position: 200% 0;
+  }
+  100% {
+    background-position: -200% 0;
+  }
+}
+
 /* Scroll shadow overlay for collapsed state */
 .code-scroll-shadow {
   position: absolute;
@@ -140,7 +146,6 @@
 }
 
 /* Default to light theme for all tokens (codeToHtml with defaultColor: false) */
-.code-block-content pre.shiki span,
 .code-content pre.shiki span {
   color: var(--shiki-light) !important;
   font-style: var(--shiki-light-font-style);
@@ -149,9 +154,6 @@
 }
 
 /* Override with dark theme colors when inside a dark context */
-.dark .code-block-content pre.shiki span,
-.dark-theme .code-block-content pre.shiki span,
-[data-appearance="dark"] .code-block-content pre.shiki span,
 .dark .code-content pre.shiki span,
 .dark-theme .code-content pre.shiki span,
 [data-appearance="dark"] .code-content pre.shiki span {