types.ts

import type { Component } from 'vue'

/**
 * File object shape for file renderer and download handler
 */
export interface FileObject {
  /** Storage URL (gs://, s3://, sftp://, or https://) */
  url?: string
  /** File content (base64 or text) */
  content?: string
  /** Filename with extension */
  filename?: string
  /** MIME type */
  mimeType?: string
  /** File size in bytes */
  size?: number
  /** Whether content is base64 encoded */
  isBase64?: boolean
  /** Additional metadata */
  metadata?: Record<string, unknown>
}

/**
 * Context passed to every renderer component
 */
export interface RendererContext {
  /** The value to render */
  value: unknown
  /** JSON path to this value (e.g., "response.body.items[0].name") */
  path: string
  /** Key name if this is an object property */
  keyName?: string
  /** Depth in the tree (0 = root) */
  depth: number
  /** Whether the value is expanded (for collapsible types) */
  expanded?: boolean
  /** Parent value (for context) */
  parent?: unknown
  /** Callback to navigate to a path */
  onNavigate?: (path: string) => void
  /** Callback to copy value */
  onCopy?: (value: unknown, path: string) => void
  /** Callback to download a file (for FileObjectRenderer) */
  onDownload?: (file: FileObject) => void | Promise<void>
}

/**
 * Props passed to renderer components
 */
export interface RendererProps {
  context: RendererContext
}

/**
 * A tester function that evaluates if a renderer should handle a value
 * Returns a priority number (higher = more specific match)
 * Returns -1 if the renderer should not handle this value
 */
export type TesterFunction = (value: unknown, context: RendererContext) => number

/**
 * A registered renderer with its component and tester
 */
export interface RegisteredRenderer {
  name: string
  component: Component
  tester: TesterFunction
}

/**
 * Options for the QuickView component
 */
export interface QuickViewOptions {
  /** Maximum depth to auto-expand (default: 2) */
  maxAutoExpandDepth?: number
  /** Maximum string length before truncation (default: 500) */
  maxStringLength?: number
  /** Maximum array items to show in preview (default: 5) */
  maxArrayPreview?: number
  /** Show copy buttons on hover */
  showCopyButtons?: boolean
  /** Custom renderers to add/override */
  renderers?: RegisteredRenderer[]
  /**
   * Handler for file downloads. Called when user clicks download on a file.
   * Use this to implement custom download logic (e.g., signed URLs, API proxy).
   * If not provided, falls back to window.open() for http(s) URLs.
   */
  onDownload?: (file: FileObject) => void | Promise<void>
  /** Use compact/dense toolbar styling for small spaces (default: false) */
  dense?: boolean
  /**
   * Indentation width in pixels per nesting level (default: 24).
   * Controls how much nested content is indented from its parent.
   * Smaller values create more compact views, larger values improve readability.
   * @example 16 // compact indentation
   * @example 32 // spacious indentation
   */
  indentWidth?: number
  /**
   * Property names to auto-expand on initial render.
   * Useful for always expanding important properties like 'body' in HTTP responses.
   * @example ['body', 'data', 'results']
   */
  defaultExpanded?: string[]
  /**
   * Expand all properties on initial render.
   * If true, expands everything up to maxAutoExpandDepth (default: 10).
   */
  expandAll?: boolean
  /**
   * Registry of key decorators to render additional content next to object keys.
   * Each decorator has a tester function that returns a priority (higher = more specific).
   * Multiple decorators can match - all matching decorators are rendered in priority order.
   *
   * @example
   * keyDecorators: [
   *   {
   *     name: 'searchable',
   *     tester: (path) => searchablePaths.has(path) ? 10 : -1,
   *     render: () => h(QIcon, { name: 'search', size: '12px' })
   *   },
   *   {
   *     name: 'required',
   *     tester: (path) => requiredPaths.has(path) ? 10 : -1,
   *     render: () => h('span', { class: 'required-star' }, '*')
   *   }
   * ]
   */
  keyDecorators?: KeyDecorator[]
}

/**
 * A key decorator that can render content next to object keys
 */
export interface KeyDecorator {
  /** Unique name for the decorator */
  name: string
  /**
   * Tester function that returns priority (higher = more specific match).
   * Return -1 if decorator should not apply to this key.
   */
  tester: (path: string, key: string, value: unknown) => number
  /**
   * Render function that returns a VNode to display.
   * Called only if tester returns >= 0.
   */
  render: (path: string, key: string, value: unknown) => unknown
}

/**
 * Detected value types for smart rendering
 */
export type DetectedType =
  | 'null'
  | 'undefined'
  | 'boolean'
  | 'number'
  | 'string'
  | 'string:url'
  | 'string:email'
  | 'string:date'
  | 'string:base64'
  | 'string:json'
  | 'string:color'
  | 'string:long'
  | 'array'
  | 'array:empty'
  | 'array:homogeneous'
  | 'object'
  | 'object:empty'
  | 'object:http-response'
  | 'object:file'
  | 'object:error'
  | 'object:date'