npm package: @quickflo/quickview
Description: Smart data visualization component for workflow outputs
Latest version: 1.4.0

# @quickflo/quickview

A Vue 3 component library for intelligently rendering complex data structures. Automatically detects and beautifully displays HTTP responses, file objects, errors, arrays, nested objects, and primitive types with built-in search, copy, and navigation.

## Features

- **Smart Type Detection** - Automatically identifies and renders HTTP responses, file objects, errors, dates, URLs, emails, colors, and more
- **Pluggable Renderer System** - Register custom renderers for domain-specific data types
- **Built-in Search** - Search across keys, values, and paths with jump-to navigation
- **Collapsible Structures** - Expand/collapse nested objects and arrays with configurable default depth
- **File Downloads** - Built-in file renderer with customizable download handler for cloud storage (GCS, S3, SFTP)
- **Copy Support** - One-click copy for individual values or entire structures
- **Quasar Integration** - Built with Quasar components for a polished UI

## Installation

```bash
npm install @quickflo/quickview
# or
pnpm add @quickflo/quickview
# or
yarn add @quickflo/quickview
```

### Peer Dependencies

QuickView requires Vue 3 and Quasar:

```bash
npm install vue quasar @quasar/extras
```

## Quick Start

```vue
<script setup>
import { QuickView } from '@quickflo/quickview'
import '@quickflo/quickview/styles'

const data = {
  status: 200,
  statusText: 'OK',
  headers: { 'content-type': 'application/json' },
  body: {
    users: [
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Bob', email: 'bob@example.com' },
    ]
  }
}
</script>

<template>
  <QuickView :value="data" />
</template>
```

## Built-in Renderers

### Primitives
- `null` / `undefined` - Styled null indicators
- `boolean` - Color-coded true/false chips
- `number` - Formatted numbers
- `string` - With smart detection for URLs, emails, dates, colors, JSON, base64

### Smart String Detection
- **URLs** - Clickable links with external icon
- **Emails** - Mailto links
- **Dates** - Formatted with relative time
- **Colors** - Hex/RGB preview swatches
- **JSON Strings** - Parsed and rendered as objects
- **Base64** - Decoded preview with copy support
- **Long Text** - Truncated with expand option

### Structures
- **Objects** - Collapsible with key-value display
- **Arrays** - Collapsible with item count, table view for homogeneous data
- **Empty** - Styled empty object/array indicators

### Domain Types
- **HTTP Response** - Status badge, collapsible headers, body preview
- **File Object** - Icon, mime type, size, download button, image preview
- **Error Object** - Error styling, stack trace, details expansion

## Options

```typescript
interface QuickViewOptions {
  // Default depth to auto-expand (default: 2)
  maxAutoExpandDepth?: number

  // Max string length before truncation (default: 500)
  maxStringLength?: number

  // Max array items in collapsed preview (default: 5)
  maxArrayPreview?: number

  // Show copy buttons on hover (default: true)
  showCopyButtons?: boolean

  // Custom renderers to add/override
  renderers?: RegisteredRenderer[]

  // Handler for file downloads (cloud storage support)
  onDownload?: (file: FileObject) => void | Promise<void>
}
```

### Example with Options

```vue
<template>
  <QuickView
    :value="workflowOutput"
    :options="{
      maxAutoExpandDepth: 3,
      onDownload: handleFileDownload
    }"
  />
</template>

<script setup>
async function handleFileDownload(file) {
  // Call your API to get a signed URL for cloud storage files
  const signedUrl = await api.getSignedUrl(file.url)
  window.open(signedUrl, '_blank')
}
</script>
```

## Custom Renderers

Register custom renderers for your domain types:

```typescript
import {
  QuickView,
  RendererRegistry,
  createDefaultRegistry
} from '@quickflo/quickview'

// Create a registry with default renderers
const registry = createDefaultRegistry()

// Add a custom renderer
registry.register({
  name: 'user-avatar',
  priority: 100,
  tester: (value) => {
    return (
      typeof value === 'object' &&
      value !== null &&
      'avatarUrl' in value &&
      'displayName' in value
    )
  },
  component: UserAvatarRenderer
})
```

```vue
<template>
  <QuickView :value="data" :registry="registry" />
</template>
```

## File Object Shape

The file renderer detects objects with this shape:

```typescript
interface FileObject {
  url?: string          // gs://, s3://, sftp://, or https://
  content?: string      // File content (base64 or text)
  filename?: string     // Display name
  mimeType?: string     // MIME type for icon/preview
  size?: number         // Size in bytes
  isBase64?: boolean    // Whether content is base64 encoded
  metadata?: Record<string, unknown>
}
```

## Styling

QuickView uses CSS custom properties for theming:

```css
.quickview {
  --qv-bg: #ffffff;
  --qv-bg-hover: #f8fafc;
  --qv-bg-selected: #e0e7ff;
  --qv-border: #e2e8f0;
  --qv-text: #1e293b;
  --qv-text-muted: #64748b;
  --qv-text-subtle: #94a3b8;
  --qv-info: #6366f1;
  --qv-success: #22c55e;
  --qv-warning: #f59e0b;
  --qv-error: #ef4444;
  --qv-mono: 'SF Mono', Menlo, Monaco, monospace;
}
```

## Development

```bash
# Install dependencies
pnpm install

# Start dev server with demo
pnpm dev

# Build library
pnpm build

# Type check
pnpm typecheck
```

## License

MIT